# mesh-host

Tier 0 of the Novox Mesh. The one thing ever installed by hand, and the only thing that changes
a machine.

```
scp mesh-host root@machine:/usr/local/bin/
mesh-host profile
```

That is the whole installation. One statically linked binary, nothing else present, no runtime
to install first ([`novox/hq` ADR 0041](https://git.novox.be/novox/hq)).

## What it is for

**Apply declared state on this machine.** Overlay membership, packet filtering, packages,
services, containers and filesystems are not six concerns it carries; they are six instances of
the one.

**It does not decide.** Anything needing knowledge of another node is the control plane's, and
the host never queries the mesh database. It receives declarations and applies them.

## What exists today

**It reports, and it has begun to apply.** It connects to nothing and listens on nothing.

```
mesh-host profile      what this machine can be asked to do
mesh-host inventory    what this machine is, and what it holds
mesh-host apply FILE   make this machine match the declaration in FILE
  --json               machine-readable
  --timeout            how long any single probe may take (default 10s)
  --store P            where the applied-state store lives (apply)
```

```
$ mesh-host profile
linux/amd64

  yes  container-runtime  29.7.2
  no   firewall           nft exited 1: Operation not permitted (you must be root)
  yes  graphical-session  x11: :1
  yes  overlay            wg0
  yes  package-manager    pacman 7.1.0
  no   privileged         effective uid 1000, not 0
  yes  service-manager    degraded

cannot be asked to: [firewall privileged]
```

Stage 2 has started: `apply` consumes a declaration (novox/hq ADR 0043) from a local file and
converges this machine, with no mesh present. The first vocabulary is the one that needs no
network — directories and files — applied in the stated order, read back, and recorded so what
was applied and no longer declared is removed, while what the host did not create never is. The
remaining resource types, sealed secrets, the link to the control plane, the pinned substrate
bundle and enrolment are designed and not yet built.

## A capability is detected, never assumed

The reason this is the first thing built rather than a detail of it.

**An installed package is not a capability.** A container client on disk with its daemon down
looks exactly like a working runtime, and a node assigned work on that basis fails at the
moment the work arrives. So every detector runs something that only succeeds if the thing is
**functioning** — the daemon is asked for its version, the package database is queried, the
firewall is asked to list a ruleset, which needs the privilege as well as the tool.

**Every verdict says how it knows.** A capability reported absent with no reason is a fault
nobody can act on. The reason is what a person reads when a node will not take work they
expected it to take.

**Exit codes are not the whole answer.** Found by running against a real machine rather than by
reasoning: `systemctl is-system-running` exits non-zero for every state except `running` —
including `degraded`, which means some units failed and the init is emphatically there. Reading
the exit code reported no service manager on a machine whose init it was. That is the same
fault in the mirror — installed-but-broken reported present, working-but-imperfect reported
absent — and both place work wrongly.

## Building

```
go test ./...                       structure and logic, and the same checks against this machine
CGO_ENABLED=0 go build -ldflags="-s -w" -o mesh-host ./cmd/mesh-host
```

Roughly 3 MB, static, no dynamic dependencies. Cross-compiles with `GOOS`/`GOARCH`; a host is
built once per architecture and copied, never built on the machine it runs on.

**Mocking the boundary is forbidden** ([`novox/hq` ADR 0034](https://git.novox.be/novox/hq)).
Every detector is exercised against a fake runner for its logic *and* against this machine for
its behaviour. The tests do not assert which capabilities a machine has — that varies, and is
the point of detecting — they assert that detection tells the truth about whatever is there.

## Where the reasoning lives

Design and decisions are in [`novox/hq`](https://git.novox.be/novox/hq), not here. This
repository carries implementation and does not carry decisions.

- `03-DESIGN/01-to-be/05-the-node-host.md` — what this is and the order it is built in
- `02-DECISIONS/0037-the-host-applies-it-does-not-decide.md` — the one concern
- `02-DECISIONS/0038-a-node-joins-by-linking-first.md` — one behaviour, two sources
- `02-DECISIONS/0039-the-link-is-the-security-boundary.md` — a node owns no password
- `02-DECISIONS/0041-the-host-depends-on-nothing.md` — why this is a static binary, and Go
- `04-ISSUES/007-an-installed-package-is-not-a-capability` — why detection works this way