felhom.eu/REPORT-wire-contract-gate.md

# REPORT — G-1: a gate for the dropped field, then the fields it found (2026-08-08)

*A non-overwritten `REPORT-<topic>.md` sibling, per `CLAUDE.md:82-87` — a parallel session shares this
clone and the shared `REPORT.md` was not touched.*

## 1. The gate's output on today's tree — failing, before anything was fixed

**This is the session.** Captured verbatim in
`documentation/tests/wire-contract-gate-2026-08-08/BEFORE.md`:

```
wire-contract gate — 210 tag(s) checked across 3 declared wire(s); 51 skipped
WIRE-CONTRACT GATE FAILED: 40 emitted field(s) cannot be received.
```

It named every one, with its emit path and its direction, and re-found **`escrow_stale`** (R-247) and
every field R-260 listed. Had it been green, the gate would not work and *that* would have been the
finding — which is not hypothetical: the night before, `deadcode` was rejected for the neighbouring
C6 class for exactly that reason.

**⚠ A count this session's prompt got wrong.** The prompt said *"465 emitted tags, eight
unreachable"*. R-260's wording was "at least eight **decision-bearing** facts", never eight tags in
total. Measured: **40** on the three declared wires. Checked against the repo, not quoted — the
prompt's own rule 6, and the second prompt claim caught that way this week.

## 2. The forty, by disposition

| # | field(s) | direction | decision | what changed |
|---|---|---|---|---|
| 1 | `oob.operator_key_configured` | agent → hub | **receive and act** | decoded (pointer); `oobDegraded` fails on a missing key and the alert names it |
| 2 | `oob.wg_handshake_age_s`, `oob.healed_at` | agent → hub | **receive, message only** | in `HostOOBRow` + the event payload; deliberately NOT in the predicate |
| 3 | `escrow_stale` | hub → controller | **receive and act** | `report.EscrowStatus.Stale`; withheld-hash told apart from hash-less. **R-247** |
| 4 | 12 host/system metric fields | both → hub | **no consumer wanted — redundant** | allowlisted: the hub bands on the `*_percent` figures from the same stanzas |
| 5 | `guests.spec.{disk_bytes,memory_bytes}` | agent → hub | **redundant** | sizing is hub-owned intent, not mirrored reality |
| 6 | `storage_targets.smart.model_name` | agent → hub | **redundant** | a display label; `smart.health` + every banded counter ARE decoded |
| 7 | `wireguard.last_handshake_age_s` | agent → hub | **redundant** | wgsync reconciles from its own state |
| 8 | 21 fields (`guest_net`+7, `selfupdate_pending`+1, `healed_recently`, `applied_at`, `mount_parity`/`_inventory`, `config_hash`, `reporting_disabled`, `stacks`, `migrated_to`, `last_db_dump`, `last_integrity_check`) | both → hub | **no consumer today, one arguably owed** | allowlisted **against R-264, OPEN**. Allowlisting is not deciding, and the entries say so |

Full per-field reasons are in the gate's own `ALLOWLIST`, each a claim someone can re-check.

## 3. Scenario F — the choice, and why

**Unknown is reported distinctly and is never `ok`.** `operator_key_configured` decodes as a
**pointer**: nil = the agent never said, which is not a value.

The version gate the prompt thought "probably right" was **rejected on a measurement**: the field and
the `oob` stanza that carries it shipped in the **same** agent version (v0.72.0, 2026-07-05), so a
stanza without the field cannot come from any released agent. The live fleet is 0.113.0 and 0.127.0;
the vouched floor is 0.127.0. Building version-gating machinery the hub does not otherwise have, for a
state no box can be in, is cost without cover. The case is still handled explicitly and pinned by a
test, because "cannot happen" is a claim this project has been burned by.

## 4. R-247 — CLOSED

The field is received, and `reconcileEscrowed` tells a **withheld** hash from a **hash-less** one.
Controller v0.209.0.

**Deliberately not folded in, and said rather than skipped:** the wrong flag on `demo-hp` is an
operator act hub-side (**R-246**, still open), and the customer-facing Hungarian card copy is
unchanged — that is UI work with its own review path.

## 5. The gate's blind spots, and its self-test

Published in the module docstring **and** in the gate's own output, because Campaign 12's C1 guard
turned out blind to one of the three shapes it was written for:

- **generic tag names are not checked** (`name`, `state`, `status`, …) — a repo-wide string test says
  nothing about them, so a drop of a generically-named field is **missed**; the gate under-reports
  rather than over-reports;
- **reachability of a NAME is not use of a VALUE**;
- **only declared ROOTS are covered** — the hub's desired-state (raw stored JSON, no typed emitter)
  and the agent's local API (no single root) are **not**;
- it reads source, not traffic; test files and `testdata/` are excluded on the receiving side
  deliberately (a tag present only in a fixture is not decodable — which is R-262 exactly).

`--selftest` plants an unreachable tag on a real root in a throwaway copy and asserts conviction:
**exit 1, planted tag named**; unplanted tree **exit 0**.

**THREE instrument defects this gate's own controls caught before it was trusted.** None was found
by review; each was found by making the gate prove something.

1. **A substring false negative** — `grep -F healed_at` also matched `privsep_healed_at`. R-260 named
   `healed_at`, so its absence from the output was the tell. Whole-token now; 40, not 39.
2. **`dr_recipe` is not wholly opaque** — its top-level section keys ARE decoded, through allow-lists
   that already swallowed `offsite_restic` for months (R-122). Now opaque only **below depth 1**.
3. **The search shelled out to `grep` and read its failure as a finding.** CI convicted **all 174**
   checked tags while the pre-push hook was green. The CI runner's image carries python3 and git and
   deliberately little else, and its `grep` does not support `--include`, so stdout was empty and
   empty was read as "absent". **A gate that silently turns a tool failure into a finding is worse
   than no gate**, and its green would have been as untrustworthy as its red. Removed the dependency
   rather than working around it: the search is pure Python now, one token index per receiving repo.

**The BEFORE capture was RE-VERIFIED, not re-generated** — the stronger claim. All 40 recorded fields
were re-tested against the new implementation: **agree=40, disagree=0**, i.e. exactly the four this
session fixed are now present and the other 36 still absent. The number stands under both
implementations.

**And the reusable half, which is about the gates and not about this gate.** The pre-push hook runs on
a workstation where every sibling repo is a real clone; CI checks out one repo, shallow. **A gate
that needs a sibling passes locally and is INCONCLUSIVE in CI — the two automated homes are not
interchangeable, and a new gate must be checked in BOTH.** The workflow's own alarm mail says a
hook-versus-CI disagreement "outranks whatever the push was for"; it did. Fixed by fetching the agent
clone in CI (`.gitea/workflows/gates.yml`), never by letting the gate skip when a sibling is absent —
that is the fail-open shape and would leave it running in neither home (R-29).

**Cost, stated plainly:** three CI runs went red (260, 261, 262) and each sent the operator an alarm
mail before run **263** went green. The alarm working is the system behaving correctly; the noise was
mine.

## 6. What `oobDegraded` says when it fails

```
Host <id>: OPERATOR ACCESS DEGRADED — the operator's authorized_key is NOT installed —
felhom-sshd is up and answering, and nobody can log in through it. The break-glass net
(auto-heal + vaulted root@pam console) is still under the box.
```

and for the unreachable-but-handled unknown:

```
… — the agent reports operator access but is too old to say whether the operator key is
installed (pre-v0.72.0) — treat entry as UNPROVEN, not working. …
```

`oobDegradedReason` is now the single source for both the predicate and the text, so the message can
never name a different fault from the one that fired. The old form derived it separately and had a
vocabulary of two.

## 7. Tests and red-proofs

New: `hub/internal/store/host_oob_decode_test.go` (4 tests, raw JSON at the decode boundary),
`hub/internal/monitor/host_oob_operatorkey_test.go` (6), plus two end-to-end tests in
`host_oob_test.go` driving JSON → store → checker → event.

**Red-proofs — 8 expected outcomes, 0 wrong, each with the mutation asserted applied:**

| mutation | assertion it applied | outcome |
|---|---|---|
| the gate on today's tree | — | **RED, naming all 40** ✔ |
| planted unreachable tag (post-fix) | self-test reports the planted tag by name | **RED on the plant, GREEN unplanted** ✔ |
| drop `operator_key_configured` from the decoder | json-tag occurrences in the decoder 2 → 1 | **RED — the false `ok` returns** ✔ |
| make the check unconditional | `MUTATED unconditional degrade` marker present | **RED — a healthy box alerts** ✔ |
| treat unknown as `ok` | `MUTATED: unknown is silently ok again` marker present | **RED — the silent pass returns** ✔ |
| all three restored | — | **GREEN** ✔ |

**The pre-existing fixture was part of the defect and was fixed too:** `oobReport()` omitted
`operator_key_configured`, so every earlier scenario ran against a report shape **no released agent
produces**. Same family as R-262.

## 8. The capability-map row about operator access

**Checked, and it was NOT claiming something untrue.** `00-capability-map.md:127` claims OOB operator
access is *implemented*, never that it is *monitored*, so no correction was owed. What was untrue sat
one layer down — the hub's own health check could not see the key — and the row now records that,
with the fix and the tests that pin it.

## 9. Gates, and what remains

`python3 scripts/repo_gates.py --fast` → **all 8 OK**, including the new `wire-contract` and
`golden-currency`. `go build ./... && go vet ./... && go test ./...` green in **hub** and
**controller** (run separately from every commit). **No `--no-verify` anywhere.**

**The one gate failure that remains is not a failure of this work:** golden **0.208.0** is baked and
byte-verified but **still not vouched**, so fresh installs receive 0.207.0. That is R-242's untouched
half and one operator Save.

## 10. Register

**R-260 CLOSED** (class gated + sharpest instance fixed), **R-247 CLOSED**, **G-1 CLOSED** in
`ROADMAP.md`. **R-264 minted and OPEN** — the twenty-one facts with no consumer, split out so that
gating the class could not be mistaken for deciding them. **Highest ID moved R-263 → R-264.**

Explicitly still open: R-246, R-255, R-256, R-257, R-258, R-259, R-261, R-262, R-263, and **C7's
test-comment half**, which Campaign 12 recorded as *owed, not done*.

## 11. Observations — noticed, NOT acted on

1. **`stacks` is the whole per-stack report object and the hub decodes none of it.** The largest
   single unconsumed structure on the controller wire; folded into R-264 rather than sized here.
2. **The hub has no version-gating machinery for report fields at all.** Not needed today (see §3),
   but the next additive field whose emitter and stanza do *not* ship together will need it, and
   there is no convention to reach for.
3. **`backup.last_db_dump` / `last_integrity_check` are backup-integrity timestamps the hub cannot
   see** — the "presence is not success" neighbourhood, and worth ranking first inside R-264 after
   guest_net.
4. **The gate cannot cover the hub's desired-state wire** because it is served as raw stored JSON.
   That is the one remaining hub→box direction with no contract check of any kind.