From 2bfb75763d605d34d422031bc2e3f30a5ec0df03 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Mon, 21 Sep 2026 14:55:04 +1000 Subject: [PATCH] docs(prds): decide where control-plane apply status is reported runtime-control-plane.md requires each process to report the version it is using or why it failed, and does not say where that report goes. It cannot be a control-plane operation: that service is the surface for editing a resource, and a status report is not an edit. It goes on the State Store contract, following the config snapshot pair, whose administrative RPCs a task-scoped grant already cannot reach. Draft, pending approval. Reviewed by three independent lenses first, per docs/prds/RULES.md. The operator lens opposed the first draft on two counts now fixed: a record replaced in place with no re-stamp would let a process that applied a version and then died keep asserting health, inverting the choice status-health-surface.md made deliberately; and the dominant failure, an unreachable State Store, can never report itself, because every apply point is reached only after the store has answered. The draft now carries instance identity and a re-stamp interval, says plainly which failures are reportable at all, and gives the three kinds of absence distinct renderings. The boundary lens required the surface be reconciled against ConfigView's reload status rather than duplicating it; apply status covers resource kinds and ReloadStatus stays the file document's only report. The contract lens established that task-grant denial needs no new rule, that the read is a list rather than a found=false singleton, and that the contract's RPC count moves from 45 to 47 in two places. Relates to archie-core-pskb. --- docs/prds/control-plane-apply-status.md | 119 ++++++++++++++++++++++++ 1 file changed, 119 insertions(+) create mode 100644 docs/prds/control-plane-apply-status.md diff --git a/docs/prds/control-plane-apply-status.md b/docs/prds/control-plane-apply-status.md new file mode 100644 index 000000000..5045a16c3 --- /dev/null +++ b/docs/prds/control-plane-apply-status.md @@ -0,0 +1,119 @@ +# Control-plane apply status + +**Status:** Draft +**Date:** 2026-09-21 +**Tracking:** `archie-core-pskb`, and `archie-core-nwa0` which depends on it + +## Outcome + +An operator who edits a control-plane resource can see which processes are +running that version, which are still on an older one, which rejected it, and +which have stopped saying anything at all. + +`docs/prds/runtime-control-plane.md` requires the first three ("Each process +reports the version it is using or why it failed. The UI shows both") and does +not say where the report goes. This decides that, and adds the fourth, because +without it a process that dies after a successful report keeps asserting +health. + +## Where the report goes + +Apply status is a State Store contract surface. `ControlPlaneService` is the +surface for editing a resource, and a status report is not an edit. The +matching precedent is the config snapshot pair: a process publishes what it +knows, the UI process reads it, and both RPCs are administrative, so a +task-scoped grant reaches neither. That denial needs no new rule; +`authorizesTaskScopedCall` names three methods and denies everything else. + +`docs/prds/state-store-contract.md` gains the pair in its inventory, and its +RPC count at two places moves from 45 to 47. + +The read returns every record as a list, including an empty one. It is not a +singleton read, so the `found=false` convention for absent single rows does not +apply to it. + +## What is reported + +One record per process instance and resource kind, replaced in place. It holds: + +- the process name and the instance identity it generated at startup; +- the resource kind; +- the version the process applied, and the error if it could not; +- the time it last reported. + +A process reports at the point it applies a resource, so the record says what +happened rather than what was intended. Nothing probes. + +Each reporting process re-stamps its records on a fixed interval. The report +time is therefore a liveness signal, not just a write timestamp: a record that +has stopped being re-stamped belongs to a process that has stopped running. + +Process names come from one shared constant naming `archied`, `archie-gateway` +and `archie-messaging`. A deployment runs at most one instance of each. A +producer that invents its own name would be indistinguishable from a process +that is down, so writer and reader are bound to that constant by test. + +## Which processes report + +- `archied` and `archie-gateway` apply every restart-required kind through + `boot.runtimeConfig`, at boot and on SIGHUP. +- `archied` also applies the live kinds it watches, and reports each update it + applies. +- `archie-messaging` applies channel settings at startup and reports that kind. + +## What can be reported, and what cannot + +A process reaches its apply point only after the State Store has answered it. +When the State Store is unreachable, the process exits or refuses to start, and +writes no record at all. An unreachable store is therefore never reported as a +failure by the process it affected. What a record can carry is the other +failure: the store answered, and the value it returned would not validate. + +The UI distinguishes three absences, and never collapses them: + +- no process applies this kind, so there is no record and none is expected; +- a process has records for other kinds but none for this one; +- a process has a record that has gone stale, meaning it is no longer running. + +## Relationship to the reload status + +Apply status covers control-plane resource kinds. `ReloadStatus` covers the +file document, and stays the only report for a SIGHUP that failed to resolve or +validate the file. The two are not merged and neither is derived from the +other. + +Writing an apply-status record is best-effort everywhere, and on the SIGHUP +path specifically it gets its own bounded context, separate from the budget the +reload spends reading the control plane. A failed report is logged and never +turned into a failed reload: the configuration it describes has already been +applied, and reporting it badly must not raise a banner saying the reload +failed. + +## What the UI shows + +The settings page shows, per resource, the stored version beside each process's +applied version, error, and how recently it reported. A process on an older +version of a restart-required resource is pending a restart. A process with an +error is failed, with the error beside it. A process whose record has gone +stale is unknown, never current. + +## Verification + +- A process that applies a resource writes a record carrying that version and + its instance identity. +- A process whose apply fails validation writes a record carrying the error and + no new version. +- A reload that fails leaves the previously applied version recorded. +- A record that stops being re-stamped renders as unknown rather than current. +- A record written under a process name outside the shared constant fails the + test that binds writer to reader. +- A task-scoped credential is refused by both RPCs. +- A failed report does not fail the reload that produced it. + +## Not included + +- History of past applies. Records are current state; resource history already + records what was written. +- Checking a live replacement before switching to it. That is + `archie-core-nwa0`, which reports its failures through this surface. +- Any change to how a resource is applied.