---
status: open
opened: 2026-09-22
located-in: []
fixed-by:
amended-design:
---

# 087 — The controller cannot tell that a node's host is too old for what it sends

## What was observed

Found in review of the adoption-mode build, 2026-09-22, by reading the code.

A host parses a declaration strictly: a field it does not know makes it refuse the whole
declaration, and nothing is applied. That is deliberate, and it is what keeps a half-understood
declaration off a machine. It also means every new field in a declaration is a flag day: hosts
must be upgraded before the controller sends it.

The controller has no record of which version of the host a node runs. It is not in what a node
reports, and it is not in the node's profile. So when a node refuses a declaration for that
reason, the mesh shows the node failing and relays the host's refusal. Nothing says *the host on
this machine is older than what the mesh now sends*, and nothing could have said so beforehand.

Adoption mode adds four such fields, one of them on the declaration of **every** node, and its
merge order exists for this reason alone: the host merges first, every machine is upgraded, then
the controller.

## Why it matters beyond this instance

Every future field in a declaration has the same flag day, and the mesh upgrades itself. A mesh
that cannot say which machines are ready for what it is about to send has to be upgraded by
someone remembering the order. The rule that a host refuses what it does not understand is right;
the missing half is that the controller should know before it sends.

## Open questions

- Should a node report the version of its host, so the controller can refuse to send a
  declaration a node cannot parse, and say which machines are behind?
- Should the mesh refuse to send a field no node understands yet, or refuse per node and say so?
- Is there a general shape here — a declaration saying which version of the host it needs — or is
  a reported version enough?