two designs, proposed and not built: a box that cannot reach Proxmox still reports why (03 §12a item 8, R-1396); the delete journal keeps an id that is not a name (05 §14.3, decision 312)

Claude-Session: https://claude.ai/code/session_0159rPz1ZhFKsS53msqPYxtS
This commit is contained in:
admin committed 2026-11-15 14:39:00 +01:00
1 parent 92853bed2c
commit 90ba98b1a0
2 files changed
+112 -1

No files matched your search

@@ -1032,6 +1032,51 @@ pinned box again and the move runs again. Tested with a cut staged at each of th
(`TestMainCallsTheConfigRepairBeforeItLoadsTheConfig`, `TestAgentJSONWritersUseTheJournalledWrite`). **Not proven: a
real power cut on a box.** The copy `agent.json.pre-pve-trust` stays, for a person; nothing reads it.
**8. A box that cannot reach Proxmox still tells the hub why `[DESIGN — proposed, not built]` (R-1396 gap 2; written 2026-11-15).**
*Today (read in source).* The agent's report starts with one call to Proxmox (`hub.Collector.Collect` →
`NodeStatus`). When that call fails — the trust does not work, Proxmox is stopped, the token was removed — `Collect`
returns an error and the cycle sends nothing. The agent goes on asking the hub for jobs, so it is alive, but the hub
gets no report: after the stale time the operator reads „host stale”, with no cause. The causes the agent knows at
that moment (`pinned_cert_changed`, `ca_mismatch`, `cert_expired`, …) stay in its journal. Seen on 2026-11-15: a
wrong CA copy could raise no alarm (it also repaired itself at the agent's start).
*Why it is not built tonight.* The smallest change is a report with almost nothing in it. But the hub reads a report
as the whole truth about a box: a report with no guests, no storage and no backups would raise „guest gone”,
„storage disconnected” and stale-backup alarms, and it would write an empty recovery recipe over the good one. So
the report's meaning changes for the hub, and every reader of a report in the hub must be read first. That is not
small (rule: a change of the report's shape for the hub stops at the design).
*The design.*
1. **The agent** sends a *short report* when the first call fails: `host_id`, `reported_at`, `sent_at`, the agent's
version and hash, the `proxmox_trust` stanza, and one new stanza
`proxmox_unreachable: {since, cause, detail}` — `cause` is a trust cause, or `no_answer`, `refused`, `timeout`,
`http_5xx`, `unauthorized`; `detail` is cut at 240 characters. **No other key is present** — no empty list that
could be read as „the box has no guests”.
2. **The agent sends it only to a hub that says it understands it.** The hub's answer to a report gains one field
(`accepts_short_report: true`); the agent remembers it in memory. To an older hub the agent stays silent, as today.
So the two sides can be released in any order, and an older hub never gets a report it would misread.
3. **The hub**, on a report that holds `proxmox_unreachable`: it updates the box's last-seen time and agent version,
runs the clock check and the trust check, and raises one operator-only alarm `proxmox_unreachable` per (box, cause)
that names the cause and since when; the first full report clears it. **Every other reader is skipped** and the
last full report stays the stored truth (guests, storage, backups, the recovery recipe, capabilities, the fill and
disk checks). The Hosts page shows the box as „reports, cannot reach Proxmox since …”, not as healthy.
4. **„Host stale” stays true to its meaning:** a box that sends short reports is not stale (it is alive), and it is
not healthy. The stale alarm is for silence; the new alarm is for this state.
*What it costs.* One list of every place in the hub that reads a host report (to be made at the build — the count is
not known today), one test per place that a short report changes nothing there, and the two new fields on the wire
(the wire gate needs both sides in one series).
*The test on a box that settles it.* demo-hp, with nothing in flight: stop `pveproxy` for 20 minutes. Expected: one
operator mail that names `no_answer` (or the cause), the Hosts page line above, NO guest, storage or backup alarm,
the stored recovery recipe unchanged (compared before and after), and the alarm cleared at the first report after
`pveproxy` starts. A second run with a wrong served certificate must name the trust cause.
*If nothing is built:* a box that loses Proxmox is „host stale” with no cause, as today; the operator reads the
cause in the box's journal.
**What changes for a pinned box when Proxmox makes a new certificate:** the first failed call names
`pinned_cert_changed`, runs the order above, and the next call works — the box is blind for one report cycle at most,
not until a person repairs it. `runbooks/RUNBOOK-agent-proxmox-pin-repair.md` stays the hand repair for an agent older
@@ -453,7 +453,7 @@ or a household. The ruling: a delete removes them, with one exception — the de
| `offsite_keys`, `offsite_windows`, `offsite_abandon_requests` | the household | the household is deleted (the purge leg, after the outside legs) | `store.PurgeCustomerResidue`; counted in the delete dialog's residue |
| `offsite_app_presence` (the hub's own record of which apps a box runs; D72, `07` §8.2f — built, not released) | the household | the household is deleted; the daily orphan sweep takes what an earlier delete left | `store.PurgeCustomerResidue`, `store.PurgeOrphanRows`. At most 400 names per household; no age limit on a row (it would move a real app's 30 days) |
| `operator_actions` (the operator's own action log) | the household | **one year after the deletion**, with `events` and `notification_log` | `store.PruneDeletedCustomerAudit`. *Decided by CC unattended on 2026-11-14; accepted by the operator on 2026-11-15 (`09` §3 decision 311):* it is an audit record of the same kind as the other two, and the one-year rule (decision 181) is the design's rule for those; the other option, at once, loses „who did what” on the day of the deletion |
| **`host_deletions`, `customer_resets`** — the delete journal | both | **never** | the ruling's one exception: an id and timestamps, no personal data. The privacy text must say so (proposed, not published) |
| **`host_deletions`, `customer_resets`** — the delete journal | both | **never** | the ruling's one exception: an id and timestamps. **An id can be a name, so this is not „no personal data”** — the design to change that is §14.3, and the privacy text waits for it (`09` §3 decision 312) |
**Rows left by boxes and households deleted before this release** (Peti's box, the test boxes of 2026-11): the daily
prune runs `store.PurgeOrphanRows` — the six tables of the first and third rows, for a box with no `hosts` row and for
@@ -468,6 +468,72 @@ its own design, because the kernel lane reads a box's old reports to know which
(`TestD73_*`), 16 mutations seen red (`audits/night-build-2026-11-14/B/redproof-hub-d73.txt`).
### 14.3 The delete journal keeps an id that is not a name `[DESIGN — proposed, not built]` (`09` §3 decision 312; written 2026-11-15)
**Why.** §14.2 says the delete journal stays for ever and holds „an id and timestamps, no personal data”. The second
half is not true. An id of a household or of a box is typed by a person and can be a name: one deleted box carried
its owner's first name, and a box's id starts with its household's id. So the privacy text cannot say „no personal
data” today, and it is not published (decision 312).
**What each journal table holds, and who reads it (read in source, 2026-11-15).**
| Table | Columns | Who reads it, and for what | For how long the reader needs the id |
|---|---|---|---|
| `host_deletions` (one row per deleted box) | `host_id`, `customer_id`, `deleted_at`, `escrow_acked` | (1) a new install of the SAME household: the sealed key package of the deleted box becomes the new box's package (`escrow_carry.go`); (2) RESET and delete of the household: they find the rows of boxes that are already gone by this list (`customer_reset.go`, `store.go` purge queries); (3) the deadline check: „did this household ever have a box?” | while the household exists; then until its delete cascade has ended |
| `customer_resets` (one row per RESET or delete attempt) | `customer_id`, `started_at`, `completed_at`, `escrow_acked`, `legs_json` (the state word of each step) | (1) „Resume”: a second press reads which steps are done; (2) the one-year rule: `PruneDeletedCustomerAudit` reads which households were deleted and when, to remove their events, mail log and action log one year later | until the cascade has ended; then one year, for the prune |
**The finding in one sentence:** every reader needs the id only while the household exists or during the one year
after its deletion. After that year nothing in the hub reads the id; what is left is the audit fact „a deletion
happened, at this time, these steps ran”.
**The two options.**
| | A — after one year the id is removed (CC's pick) | B — after one year the id is replaced by a code |
|---|---|---|
| What stays in a journal row after the year | the row number, the times, the step states; the id columns hold `removed` | the same, and a code made from the id with a key only the hub holds (the same id always gives the same code) |
| What it keeps of the journal's purpose | „a household was deleted on this day, in these steps” — the count and the times | the same, and one more answer: with the id in hand, the operator can ask „was THIS id deleted, and when?” |
| What it costs | after the year, the question „when was household X deleted?” is answered from the operator's own records, not from the hub | the code is made from the name, so in law it is still data about that person (a pseudonym), and the hub holds the key; the privacy sentence gets longer and weaker; one more secret to keep and to rotate |
| How the rows that exist are changed | no row changes on the release day; the daily prune does it for each household when its year ends (the first one on 2027-09-25) | the same day and step, with the code in place of `removed` |
| What is built | one more statement in `PruneDeletedCustomerAudit` (the step that already runs at the year's end), and the same for the `host_deletions` rows of that household | the same, plus the key and its handling |
**CC's pick: A.** The reason: the sentence to the household can then be short and true, and nothing in the product
needs the id after the year. B keeps an answer that only the operator would ask, at the price of keeping the very
thing the sentence must not promise away.
**Rules that hold in both options.**
1. Nothing changes while the household exists, and nothing during the year: the readers above need the id.
2. The step runs in the same transaction as the one-year prune of that household, so there is no day on which the
log is gone and the id is not.
3. A box deleted from a household that still exists keeps its `host_deletions` row with its id: the household's own
id is in the hub anyway. The row follows its household.
4. A household whose delete never ended (a step failed and nobody pressed Resume) keeps its rows with the id — the
year starts at `completed_at`. The System page should name such a household; today it does not (to read at the
build).
5. `legs_json` holds a state word per step today (`pending`, `ok`, `failed`, `manual`), no account name. A test must
pin that, because a later change could put a name there.
6. **Not solved by this, and said to the operator:** the hub's own database snapshots (up to 8 weeks on ep0) hold
the old rows until they age out; the mails the hub sent to the operator hold the id for ever in his mailbox.
7. **Not chosen, and why:** an id that the hub makes itself (a number in place of a typed name) would fix this at the
source. It changes every page, every mail and every box's config, and the ids that exist would still be names.
**The privacy sentence that would then be true — a proposal, NOT published.**
- HU: „A fiók törlése után a rendszer egy évig megőrzi a műveleti naplót és a törlés bejegyzését a fiók
azonosítójával együtt. Egy év után a naplót törli, a törlés bejegyzéséből pedig eltávolítja az azonosítót: csak a
törlés időpontja marad meg.”
- EN: "After an account is deleted, the system keeps the action log and the record of the deletion, with the account's
identifier, for one year. After one year it deletes the log and removes the identifier from the record: only the
time of the deletion stays."
**What a test must show at the build:** after the year's prune of one household, no row in the two journal tables
holds its id or its boxes' ids (searched as text, with a look-alike id that must stay); the rows are still there with
their times; a household deleted 364 days ago keeps its id; a household that still exists keeps everything.
**If nothing is decided:** the journal keeps ids that can be names with no end, and the privacy sentence stays
unpublished.
## 15. Customer e-mails — what the hub writes to a household [hub v0.118.0, R-558]
**The section this document did not have.** The hub composes every sentence a household reads before