183 findings across 28 of 46 PRDs, of which 150 were file:line citations. Two
were already hard-broken: one named a file that no longer exists, one pointed
past the end of its file. The rest resolved to a line that still exists,
which is the worse failure -- a citation that silently drifted onto unrelated
code still reads as authoritative.
Citations now name the file and the symbol. Dated status markers become the
decision they carried ("Status 2026-09-05: resolved" -> "Resolved"), since
whether a question is answered is design information and when it was answered
is not. Progress inventories become scope statements: mcp-tool-completion now
fences what is out of scope rather than reporting what shipped.
status-health-surface drops phase-completion from its headings and keeps the
rule that earned them, that a reported field must have a truthful source.
eda-playbook-engine.md was the worst file and my own t2db.23 status block was
part of why; it is rewritten as the resolution it records.
118 lines
5.1 KiB
Markdown
118 lines
5.1 KiB
Markdown
# Control-plane apply status
|
|
|
|
**Status:** Approved
|
|
**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 reporting.
|
|
|
|
`docs/prds/runtime-control-plane.md` requires this and does not say where the
|
|
report goes. This decides that.
|
|
|
|
## 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
|
|
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 all records as a list, including an empty one. The
|
|
`found=false` convention for absent single rows does not apply.
|
|
|
|
## What is reported
|
|
|
|
One record per process and resource kind, replaced in place. It holds the
|
|
process name, the resource kind, the version applied, the error if the process
|
|
could not apply it, and the time it reported.
|
|
|
|
Each process re-stamps its records every 30 seconds. A record is stale once it
|
|
is older than 90 seconds, and a stale record means the process that wrote it is
|
|
no longer running. The report time is therefore a liveness signal, not only a
|
|
write timestamp.
|
|
|
|
A process reports at the point it applies a resource, so the record says what
|
|
happened rather than what was intended. Nothing probes.
|
|
|
|
Process names come from one shared constant naming `archied`, `archie-gateway`
|
|
and `archie-messaging`. A deployment runs at most one of each. Writer and
|
|
reader are bound to that constant by test, because a drifted name is
|
|
indistinguishable from a process that never reported.
|
|
|
|
## 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. An unreachable store is never reported as a failure by the
|
|
process it affected. A record carries the other failure: the store answered,
|
|
and the value would not validate.
|
|
|
|
Absence has two meanings and the UI never collapses them: no process applies
|
|
this kind, or a process that applies other kinds has not reported this one.
|
|
|
|
## 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 it. Neither is derived from the other.
|
|
|
|
Writing a record is best-effort. On the SIGHUP path it takes its own bounded
|
|
context, separate from the budget the reload spends reading the control plane,
|
|
and a failed write is logged rather than turned into a failed reload.
|
|
|
|
## What the UI shows
|
|
|
|
The settings page shows, per resource, the stored version beside each process's
|
|
applied version, error, and report time. 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 is stale is unknown,
|
|
never current.
|
|
|
|
## A record outlives the process that wrote it
|
|
|
|
Records are replaced in place, so a process that applies a version and then
|
|
stops would otherwise leave a record asserting that version indefinitely, and
|
|
the settings page would show a dead process as current.
|
|
`docs/prds/status-health-surface.md` faced the same choice and stamped the start
|
|
of a poll pass so a wedged poller reads as stale rather than healthy.
|
|
|
|
Settled: the re-stamp above. The alternatives considered were
|
|
carrying the instance identity generated at process start, which detects a
|
|
restart but not a death, and accepting the limitation with the page saying so.
|
|
|
|
## Verification
|
|
|
|
- A process that applies a resource writes a record carrying that version.
|
|
- 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 written under a process name outside the shared constant fails the
|
|
test binding writer to reader.
|
|
- A task-scoped credential is refused by both RPCs.
|
|
- A failed report does not fail the reload that produced it.
|
|
- A record that stops being re-stamped renders as unknown rather than current.
|
|
|
|
## 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.
|