Jean-Gabriel Gill-Couture
020ebcb1f9
The previous e2e harness handrolled k8s manifests in `stack.rs`,
bypassing the Score-Topology-Interpret machinery harmony exists to
provide. This commit:
1. **ADR-023** codifies the rules: deploy with Scores (not
manifests), e2e uses the same Scores as production, one Score
per component, deploy blocks on smoke-test success, deploy logic
lives in `*-deploy` crates, topologies are compile-time,
thiserror over anyhow. CLAUDE.md mirrors the principles.
2. **New `fleet/harmony-fleet-deploy` crate** is the canonical home
for fleet-component Scores:
- `FleetOperatorScore` + helm-chart generator + `install_crds`
moved out of `harmony::modules::fleet::operator` (they should
never have lived in `harmony` core). `FleetServerScore`
(composite of NATS + operator + Zitadel + callout) moved too.
- New `FleetNatsScore` (preset over `NatsHelmChartScore` with
fleet's required values; v1 supports `UserPass` auth, callout
mode reserved on the public API for PR 1.5).
- New `FleetAgentScore` with `FleetAgentTarget::Pod`; `Vm`
target is a future variant that absorbs `FleetDeviceSetupScore`.
- `harmony-fleet-deploy` binary built on the existing
`harmony_cli` crate — no new CLI scaffolding.
3. **Operator runtime binary trimmed**: `Install` and `Chart`
subcommands removed; both jobs now belong to
`harmony-fleet-deploy`. The runtime binary becomes leaner.
4. **E2E harness rewritten** as a thin Score composer:
`harmony-fleet-e2e/src/stack.rs` deploys the stack via
`FleetNatsScore` + `FleetAgentScore`. The inline NATS manifest
factory and the bespoke agent Pod renderer are gone.
- Bring-up runs once per test binary via `shared_stack` +
`tokio::sync::OnceCell` (matches the `fleet_e2e_demo` pattern).
- Stale `e2e-*` namespaces from prior runs get pruned at
startup so the leaks the OnceCell creates don't compound.
5. **`thiserror` for the agent's `CommandServer`** — replaces the
anyhow-based surface with typed `CommandError` /
`CommandServerError`.
6. **Memory** captures eight load-bearing principles (saved to
`~/.claude/projects/.../memory/`) so future sessions don't drift
back into manifest-handrolling.
Verified: `cargo test -p harmony-fleet-e2e --test ping` green
end-to-end against k3d in 25s warm.
Architecture Decision Records
An Architecture Decision Record (ADR) documents a significant architectural decision made during the development of Harmony — along with its context, rationale, and consequences.
Why We Use ADRs
As a platform engineering framework used by a team, Harmony accumulates technical decisions over time. ADRs help us:
- Track rationale — understand why a decision was made, not just what was decided
- ** onboard new contributors** — the "why" is preserved even when team membership changes
- Avoid repeating past mistakes — previous decisions and their context are searchable
- Manage technical debt — ADRs make it easier to revisit and revise past choices
An ADR captures a decision at a point in time. It is not a specification — it is a record of reasoning.
ADR Format
Every ADR follows this structure:
| Section | Purpose |
|---|---|
| Status | Proposed / Pending / Accepted / Implemented / Deprecated |
| Context | The problem or background — the "why" behind this decision |
| Decision | The chosen solution or direction |
| Rationale | Reasoning behind the decision |
| Consequences | Both positive and negative outcomes |
| Alternatives considered | Other options that were evaluated |
| Additional Notes | Supplementary context, links, or open questions |
ADR Index
| Number | Title | Status |
|---|---|---|
| 000 | ADR Template | Reference |
| 001 | Why Rust | Accepted |
| 002 | Hexagonal Architecture | Accepted |
| 003 | Infrastructure Abstractions | Accepted |
| 004 | iPXE | Accepted |
| 005 | Interactive Project | Proposed |
| 006 | Secret Management | Accepted |
| 007 | Default Runtime | Accepted |
| 008 | Score Display Formatting | Proposed |
| 009 | Helm and Kustomize Handling | Accepted |
| 010 | Monitoring and Alerting | Accepted |
| 011 | Multi-Tenant Cluster | Accepted |
| 012 | Project Delivery Automation | Proposed |
| 013 | Monitoring Notifications | Accepted |
| 015 | Higher Order Topologies | Proposed |
| 016 | Harmony Agent and Global Mesh | Proposed |
| 017-1 | NATS Clusters Interconnection Topology | Proposed |
| 018 | Template Hydration for Workload Deployment | Proposed |
| 019 | Network Bond Setup | Proposed |
| 020-1 | Zitadel + OpenBao Secure Config Store | Accepted |
| 020 | Interactive Configuration Crate | Proposed |
| 022 | Fleet Agent Upgrade Procedure | Accepted |
Contributing
When making a significant technical change:
- Check existing ADRs — the decision may already be documented
- Create a new ADR using the template if the change warrants architectural discussion
- Set status to Proposed and open it for team review
- Once accepted and implemented, update the status accordingly