# 0058 — Complete distributed services composition

Status: Proposed; implementation and evidence are recorded in
[DD-0058](../dd/0058-distributed-services-composition.md).
Date: 24 October 2026. Stacked on ADR-0051 and ADR-0056.

## Decision

A complete distributed site is one closed Argo CD composition rooted at
`gitops/distributed-services-root-app.yaml`. It installs exactly nine child
Applications: `argocd`, `pharos-platform-routes`, `pharos-infra`, `gitlab`,
`waldur`, `llm`, `pharos`, `pharos-site-runtime` and `themelio-compat`. An extra,
missing or development-owned Application fails before delivery. The Site Runtime
is installed but remains paused until its production owners are connected.

The retained `themelio-compat` service is mandatory and active until every route
has been migrated to the new Themelio service under an explicit handover. The
composition must not treat the new Themelio as complete while any retained route
still depends on the compatibility service. Its public origin, OIDC binding,
provider tokens and image digests are part of the same exact-commit delivery.

Development AAI, browser aliases, Mailpit and Waldur seed data do not belong to a
complete site. External AAI is supplied privately on the administration machine.
Its file must be mode `0600`, bind all three registered clients and contain public
issuer metadata and trust material. The plan records only its canonical
fingerprint. Delivery rejects changed or missing identity input before a cluster
write, then applies consumer Secrets from stdin so credentials do not enter Git,
Argo values, command arguments, public state or evidence.

Every service origin is an explicit HTTPS authority on port 443 with no path,
credentials, query or fragment. Route values carry the exact catalogue checksum,
active profiles and Ceph certificate hash to the route chart. Images built in the
cluster are pinned by digest. Delivery waits for the complete child set at the
reviewed commit, including successful provider hooks, before recording success.
The Pharos browser and Site API use distinct public hosts. The Site API exposes
only its native command and SSH-access prefixes, authenticates requests with
scoped bearer grants and requires no browser OIDC redirect registration. The
gateway verifies the HTTPS backend against the internal Site API trust.

The disposable `icaruscloudlab` environment remains foundation-only until it has
approved public origins and external identity. A site with an existing
foundation must use the reviewed writer-fencing cutover; enabling the composition
does not authorise replacing existing application writers.

## Consequences

GitLab, Waldur, routes and retained Themelio share one activation boundary. A
failed identity, provider-token or child-health gate leaves the previous ready
delivery authoritative. Route migration can remove `themelio-compat` only through
a later decision that names the final migrated route set and removes its provider
exceptions. A new distributed environment must supply public bindings in committed
policy and private AAI material on its selected administration machine.