harmony/docs/adr/024-fleet-platform-capability-decomposition.md

# Architecture Decision Record: Fleet Platform — Capability Decomposition

Initial Author: Jean-Gabriel Gill-Couture (with research by Claude)

Initial Date: 2026-05-20

Last Updated Date: 2026-05-20

## Status

**Draft — under review.** Captures the proposed shape for review;
not yet locked. If accepted, supersedes the as-built layout of
`harmony/src/modules/fleet/` documented in ADR-023's first
revision.

## Context

The fleet platform shipped under `feat/iot-walking-skeleton`
spans three concerns that today share two locations:

1. **Domain logic** — what a `FleetDevice` is, what a
   `FleetDeployment` looks like, what the reconciler-contracts
   wire types mean.
2. **Adapters** — concrete NATS, Zitadel, Kubernetes, Helm
   integrations that drive the domain.
3. **Deploy procedures** — how to bring up the operator, agent,
   NATS, Zitadel as Scores against a Topology.

Today these live in `harmony/src/modules/fleet/` (mixed), the
`harmony-reconciler-contracts` crate (wire types only), the
`harmony-fleet-deploy` crate (Scores for deploy), and the
`harmony-fleet-operator`/`harmony-fleet-agent` binaries
(runtime). The boundary between domain and adapter is not
type-level: `harmony/src/modules/fleet/setup_score.rs` for
example reaches into Zitadel, NATS, Kube, and Helm directly.
Anyone wanting to swap NATS for a different transport would
touch every fleet file.

ADR-023 already addressed the *deploy*-side of this (deploy
Scores live in `*-deploy` crates, not in `harmony` core). This
ADR proposes the *domain*-side decomposition: pull a thin
fleet-domain crate above the existing reconciler-contracts, push
provider-specific code into adapter crates, and re-direct the
deploy crate to consume the domain rather than the framework
primitives directly.

## Decision (proposed)

Five crates, layered by dependency direction:

```
harmony-reconciler-contracts      (existing — wire types only)
        ▲
        │
harmony-fleet-domain               (new — domain records + capability traits)
        ▲
        │
harmony-fleet-adapters-*           (new — one crate per provider)
        ▲                          (nats, zitadel, kube)
        │
harmony-fleet-deploy               (existing — bring-up Scores)
harmony-fleet-operator             (existing — daemon)
harmony-fleet-agent                (existing — daemon)
```

### `harmony-fleet-domain`

The domain crate. Depends only on `harmony-reconciler-contracts`
and `harmony_types`. Holds:

- **Domain records**: `FleetDevice`, `FleetDeployment`,
  `FleetState`, `EnrollmentIntent`, `DeviceCredential`.
- **Capability traits**: `DeviceRegistry`,
  `DesiredStatePublisher`, `ObservedStateConsumer`,
  `IdentityProvider`, `AgentLifecycle`. These are the seam
  between domain logic and provider-specific implementations.

### `harmony-fleet-adapters-nats`, `-zitadel`, `-kube`

One crate per provider. Each implements the capability traits
above for its specific backend:

- `nats` — `NatsDeviceRegistry`, `NatsDesiredStatePublisher`,
  `NatsObservedStateConsumer`.
- `zitadel` — `ZitadelIdentityProvider`, machine-user
  provisioning, JWT-bearer minting.
- `kube` — `KubeFleetReflector` writes `Device` and
  `Deployment` CRDs as a *reflection* of domain state, not as
  the source of truth. CRD types move here from
  `harmony-fleet-operator`.

### `harmony-fleet-deploy`

Stays as the home for `FleetOperatorScore`, `FleetAgentScore`,
`FleetNatsScore`, `FleetCalloutScore`. Updates: imports
`harmony-fleet-domain` for types, uses
`harmony-fleet-adapters-*` to compose Scores against capability
traits rather than reaching directly into NATS/Zitadel client
crates.

### Direction of dependency

The fleet *domain* doesn't depend on the framework. The
framework's *deploy procedures* depend on the fleet's domain.
Inversion of today's direction, where `harmony::modules::fleet`
imports from `harmony_secret`, `harmony_zitadel_auth`, NATS
client crates, kube client crates, etc.

After this ADR is implemented, `harmony::modules::fleet`
disappears entirely. `harmony` core stays focused on framework
primitives.

## Open questions

These are the decision points pending review — flagged so the
review has concrete pivots:

- **Q1.** Is `IdentityProvider` the right capability name, or
  should we name the two distinct concerns separately
  (`DeviceCredentialMinter`, `OperatorTokenProvider`)? CLAUDE.md
  rule says "if reality has two distinct concerns, two
  traits."
- **Q2.** Should the `Device` CRD exist at all, or should the
  agent publish to a kube `Node` (per the alternative-D
  direction)? Today's mid-ground (own CRD that mirrors `Node`)
  arguably the worst of both worlds.
- **Q3.** Where does `ReconcileScore`'s adjacently-tagged enum
  live? It's the canonical wire seam between operator and
  agent. Should sit in `harmony-reconciler-contracts` (so both
  binaries import only that crate); confirm before the move.
- **Q4.** Does this redesign block the v0.1 production push, or
  does it land in v0.2 alongside the agent-upgrade work
  (ADR-022)? Public API churn after a customer is on it is more
  expensive than a 3-day delay before they are. Recommendation:
  ship the redesign first.
- **Q5.** Where do runtime tools (the `harmony-fleet` CLI plugin,
  the operator's frontend) sit in the dependency graph? If they
  depend on `harmony-fleet-domain` only, they build without
  pulling in helm/kube/ansible at compile time — which is also
  the right shape for the device-side enrollment binary
  (currently feature-gated).

## Out of scope

- **Alternative D (kube-native devices).** A future v2.0
  destination, not v0.1 or v0.2 work. Captured as the long-term
  direction; the capability traits in this ADR are the
  intentional seam that makes the migration possible later.
- **Topology decomposition.** Whether `K8sBareTopology` /
  `K8sAnywhereTopology` should themselves be capability sets is a
  separate concern. Tracked as a working draft at
  `docs/adr/drafts/topology-proliferation.md`.

## Consequences

If accepted:

- New deployable fleet components author their Scores against
  capability traits in `harmony-fleet-domain`, not against
  provider clients directly. Swapping NATS for a different
  transport becomes a single-crate change.
- CRD types move out of operator code and into
  `harmony-fleet-adapters-kube`. Operator depends on adapter
  crate; runtime binary stays slim.
- `harmony` core has no fleet code. The framework's `modules/`
  directory is reserved for general-purpose primitives (DNS,
  K8s, Helm, NATS, PostgreSQL, …); domain-specific code lives
  in its own crate tree.
- Future fleet adapters (a different transport, a different
  identity provider) are additive: one new crate, no changes to
  domain or deploy.

## References

- `ROADMAP/fleet_platform/architecture_review.md` §§4–5 —
  comparison matrix and Alternative-B rationale from which this
  ADR is extracted.
- `docs/adr/023-deploy-architecture.md` — companion ADR for the
  deploy-side rules. This ADR is the domain-side companion.
- `docs/adr/022-fleet-agent-upgrade.md` — the agent-upgrade
  procedure, which sits cleanly on top of the
  `AgentLifecycle` capability proposed here.