From 90ba98b1a06aca0940c13f799f9bb381114bf011 Mon Sep 17 00:00:00 2001 From: kisfenyo Date: Sun, 15 Nov 2026 14:39:00 +0100 Subject: [PATCH] =?UTF-8?q?two=20designs,=20proposed=20and=20not=20built:?= =?UTF-8?q?=20a=20box=20that=20cannot=20reach=20Proxmox=20still=20reports?= =?UTF-8?q?=20why=20(03=20=C2=A712a=20item=208,=20R-1396);=20the=20delete?= =?UTF-8?q?=20journal=20keeps=20an=20id=20that=20is=20not=20a=20name=20(05?= =?UTF-8?q?=20=C2=A714.3,=20decision=20312)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Claude-Session: https://claude.ai/code/session_0159rPz1ZhFKsS53msqPYxtS --- documentation/architecture/03-host-agent.md | 45 ++++++++++++ .../architecture/05-hub-architecture.md | 68 ++++++++++++++++++- 2 files changed, 112 insertions(+), 1 deletion(-) diff --git a/documentation/architecture/03-host-agent.md b/documentation/architecture/03-host-agent.md index 5abcd238..381bc04e 100644 --- a/documentation/architecture/03-host-agent.md +++ b/documentation/architecture/03-host-agent.md @@ -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 diff --git a/documentation/architecture/05-hub-architecture.md b/documentation/architecture/05-hub-architecture.md index 2de101e4..3b397da5 100644 --- a/documentation/architecture/05-hub-architecture.md +++ b/documentation/architecture/05-hub-architecture.md @@ -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