Who declares the service directory

Who declares it

Operators, through registry commits. placement move is the only path that changes which host is active, and it commits through the registry's compare-and-swap against the generation it read. service directory consumer add declares that a consumer may use a service; resolution applies that consumer capability policy.

connect --consumer CONSUMER uses the fleet resolver's consumer admission and placement fence even with --no-verify. An undeclared consumer is refused; a missing service is not_found; a malformed declaration is config; a placement move in progress is infra_down. With --json, refusals use the same structured error envelope as other Stado commands. Consumer-resolution refusals include details.route_state: undeclared for an unknown service, invalid_declaration for an invalid declaration, refused for denied consumer admission, or unavailable for a placement transaction. An unavailable refusal names the move that holds the service: its transaction id, profile, source and destination host and started_at, and points at stado placement transactions and stado placement release. details.service and details.consumer identify the requested route; details.machine identifies the machine executing discovery, not the service's placement host. Clients use these schema values rather than classifying message wording. A declaration refusal is not evidence of a failed transport and must not be retried through a relay to bypass admission.

Caller-route declaration failures carry the same context: an unreadable resolver declaration, missing consumer adapter, missing caller endpoint, missing placement or port reports invalid_declaration. The original error code is retained: a missing adapter is not_found, while malformed routing is config. An ambiguous adapter choice remains a usage refusal; failed transport remains infra_down. Desktop retains these details in Complete operation receipt.

Every answer connect reads from the directory names the service directory generation that decided it: generation in the --json answer, and details.generation in every refusal given after the registry document was read (consumer admission, an undeclared service, a caller route, a placement that did not answer). A refusal given before any document could be read carries none, and one this host's own statement decides — reading its stado service directory beside statement — states details.generation: null with details.decided_by: "this host's own statement", since no directory generation follows a change of it. A details.generation says which document was read, not that the document decided the refusal: a refusal the resolution could not finish (an infrastructure failure, retryable: true) carries the generation too. A caller that keeps an answer holds it only while this machine's resolver publishes the same generation in ~/.stado/resolver-state.json, and only a refusal whose envelope says retryable: false and names a generation; Oko's kept lookups do exactly that, and read what is kept again once they hold the lookup lock or are refused it, so a lookup that waited for another, or one that does not stand behind it, answers from what that one kept. A service that declares no scheme is spoken to with the scheme of its endpoint on its active host; one that declares neither is refused as invalid_declaration with <name> declares no scheme and no endpoint on <host> to read one from. A registry that cannot say which machine runs the command refuses the answer with its cause instead of treating the machine as unnamed.

For a remote placement, the caller receives its declared resolver adapter or its own endpoints[HOST].url, never a guessed address made from the serving host and its port. Without either route, the refusal names the caller host and service and points to consumer add --target HOST. In Desktop, Hosts → Routes → Available operations… → Resolve a consumer's service route and diagnose its connection exposes the consumer, caller host and optional declaration-only read. A route computed for another host is not a probe from that host.

stado service directory doctor brama --consumer tama --json diagnoses the route from the machine running the command. Unlike a declaration-only connect, it requires consumer admission and an actual HTTP answer; it has no --no-verify or remote --target mode. It uses the same resolver, refusal fields and persisted connection observations as connect. A missing service names the requested entry in details.service; a refused consumer remains refused, rather than being diagnosed as missing infrastructure. An HTTP response proves reachability only, not application authorization or a model verdict; inspect status and use the consuming product's diagnostic for its authenticated operation. Desktop exposes the same check through Hosts → Routes → Available operations… → Diagnose this host's admitted service connection, executed on the selected API host.

When the consumer also needs a local address, pass --target HOST. That host hands out the loopback port its resolver adapter listens on (stado host local port, run there), and the command commits the consumer's capabilities and the host's resolver adapter in one registry generation and prints the address it recorded. A consumer the host already routes keeps its address, so declaring it again never moves a port under a running client; --reassign gives that existing adapter a port the host hands out now, and the consumer's adapters on other hosts stay as they are. Omitting --capability preserves an existing consumer's capabilities. The target must already declare a resolver; this command does not install one, and an unknown target or a target without a resolver is refused with the registry unchanged.

service directory consumer remove removes the consumer's authorization and its adapters on every target in the same commit. It leaves other consumers alone. Neither command issues, widens or revokes a Skarbiec grant.

The running resolver observes adapter changes through its ordinary registry refresh and exits so its declared supervisor can apply the new listeners. No manual restart is part of this operation. A successful declaration records desired state; verify the consumer's actual connection before reporting it ready.

For example, after selecting the declared service, consumer, resolver host and required capability:

stado service directory consumer add "$SERVICE" "$CONSUMER" \
  --target "$HOST" --capability "$CAPABILITY" --json
stado service directory connect "$SERVICE" --consumer "$CONSUMER" --json
stado service directory consumer remove "$SERVICE" "$CONSUMER" --json

Stado Desktop exposes the same mutations under Hosts → Routes → Available operations… as Declare or update a consumer and its route and Remove a consumer and all its resolver bindings. The review shows the exact command. The selected Stado API executes it and returns the full output and failure receipt; Desktop does not silently edit a local registry. The operator console asks for confirmation before any request it does not judge a read from the command's own help, such as consumer add, consumer remove and publish.