A domain is named up to four different things across its layers

[retr0h]

The provider directory, the agent processor, the URL segment and the SDK service disagree about what a domain is called. Four naming systems, diverging in four different ways.

The divergences

provider directory	agent processor	URL segment	SDK service
node/apt	package	package	package
node/mem	—	memory	memory
container/docker	docker	container	docker
scheduled/cron	schedule	schedule	cron
node/host	—	hostname, os, uptime	hostname, os, uptime
network/netinfo, network/netplan, network/ping	network, interface, route	network	dns, interface, route, ping

Four kinds of mismatch, which is why there is no mechanical fix:

• abbreviation — mem against memory
• tool against concept — apt against package, docker against container, cron against schedule
• one provider, several URLs — host becomes hostname, os and uptime
• several providers, one URL — netinfo, netplan and ping all become network

Reproduce:

# URL segments
grep -ho '^  /api/node/{hostname}/[a-z0-9/{}_-]*' internal/controller/api/gen/api.yaml \
  | sed 's|.*{hostname}/||' | cut -d/ -f1 | sort -u

# provider directories
find internal/provider -mindepth 2 -maxdepth 2 -type d -not -name mocks | sort

# agent processors
ls internal/agent/processor_*.go | sed 's|.*processor_||;s|\.go||' | grep -v _public_test

Why it is worth fixing rather than living with

Adding a domain means touching all of these layers. add-a-domain tells a contributor to pick a reference domain and search for its name across the repository to check nothing was missed. That check does not work when the name changes between layers, and it is the only check there is for cross-layer completeness.

It also makes the API harder to reason about from the outside: /api/node/{hostname}/container is served by a provider called docker and an SDK service called docker, so a reader following either direction lands somewhere differently named.

Why now

v0.1.0 was cut today and nothing is on v1. A URL change is breaking, and it will never be cheaper than it is at v0.x. Doing it after v1.0.0 means a major version for a rename.

Not proposing a scheme here

The scheme is the decision. Two defensible directions:

• the URL wins, because it is the public contract, and providers are renamed to match
• the concept wins, with both renamed where they currently name a tool, so docker stays the implementation of a container domain

The one-provider-to-several-URLs case needs its own answer either way, since host genuinely serves three resources and splitting it is not obviously right.

Settling it in components/osapi/domains.md first means new domains inherit the rule rather than copying whichever neighbour they happened to read. Related: #565, which has the same shape for error prefixes.

Blocked on this

Per-domain pages in the design repo. Naming pages after a scheme that is about to change moves the problem rather than solving it.

[retr0h]

Resolved. The rule is in osapi-io/specs#243, the code in #569, the docs in #570.

The rule turned out to be a different question than this issue assumed. Not "which layer wins" but does the caller choose the tool, or does the host?

• A caller chooses a container runtime, so /container/docker names it and Podman becomes /container/podman beside it.
• A caller does not choose a package manager, so /package hides apt. A fleet-wide install cannot require knowing which hosts run Debian.
• /ntp and /schedule are the second shape: chrony and cron sit behind the entrypoint, swappable.

Run over the four domains, only /schedule/cron failed, so the change was much smaller than this issue implied.

What moved

/schedule/cron      ->  /schedule
cron:read/write     ->  schedule:read/write
client/cron.go      ->  client/schedule.go
provider/scheduled/ ->  provider/schedule/
api/node/docker/    ->  api/node/container/   (with docker_*.go files)
processor_docker.go ->  processor_container.go
node/mem            ->  node/memory

What did not, and why that is the point

provider/container/docker and provider/network/netplan/* keep their nesting. The provider tree groups by implementation so a second driver is a new directory rather than scattered files, which means it is allowed to be deeper than the URL. node/apt and node/ntp keep hiding their drivers.

26 docs mention docker and none needed changing.

Not resolved here: osapi-orchestrator still imports Client.Cron and needs a tagged osapi release before it can move.