docs: §8.2f after the independent review — told is told at an address; a plain app name; failed tries count; what is still open (the kept address, two reporters)

Claude-Session: https://claude.ai/code/session_0159rPz1ZhFKsS53msqPYxtS
This commit is contained in:
admin committed 2026-11-15 17:35:38 +01:00
1 parent efea838203
commit 0a53315b1b
3 files changed
+42 -10

No files matched your search

+1 -1
View File
@@ -79,7 +79,7 @@
| `offsitekeys` snapshot watch + `store.Get/SetOffsiteSnapshotListing` / `OffsiteRunTimesSince` (v0.158.0, R-895 slice 2) | hub/internal/offsitekeys/snapshot_watch.go, hub/internal/store/offsite_snapshots.go | — | Judging the 07:10 `snapshots/` listing against yesterday's (baseline in `hub_settings`) and the box's reported runs | Raises `offsite_snapshots_vanished` / `_unexplained` — operator-only and hub-origin (NOT in `allowedEventTypes`). The first listing is a baseline; a move-aside or RESET drops it. |
| `store.NoteAppList` / `AppPresences` + `offsitekeys.agreeEnded` (D72/D84, `07` §8.2f) | hub/internal/store/offsite_ended.go, hub/internal/offsitekeys/ended.go | `NoteAppList(customerID, deployed, claimed, now)`; `agreeEnded(now, presence, notices, listing, haveListing, claims)` | The hub's OWN record of when an app left a box's app list (fed by `handleReport`), and the decision which snapshot ids of ended apps a window may remove outside its cap | **The box's dates decide nothing.** An id is agreed only when its app has been absent 30 days by the hub's clock AND the hub's own listing shows the file older than that absence. `WindowCredit.CapExplains` is the cap's part, `EndedIDs` the agreed ids — a reader that explains ids by name must not also spend `Explains`. **After the review of 2026-11-15:** one window agrees to at most the cap's size from the hub's OWN count (`endedCap`/`boundEndedToCap`); a request for more than half of the store waits a week — its first sight is the hub's own row (`store.NoteLargeEndedRequest`, key `largeSetKey` = a hash of the whole app set), never a search of text a box could write; `store.NoteAppListClaims` returns never-seen apps once for the operator's warning; a claimed name that is not an app name is written nowhere (`ledgerName`). |
| `notify.householdReceiptEvents` + `Dispatcher.SendEndNotice` (D84; the notice lock, `09` §3 decision 315) | hub/internal/notify/end_notice.go | register; `SendEndNotice(customerID, app, ends) (EndNoticeOutcome, why)` | The mail that tells the household about its own press (one type: `offsite_end_scheduled`). **The box's event mails nobody**: the hub sends the notice from its own state (`api.endNotices`, at every report, until the mail service accepts it) | Bypasses the household's group switches; the hub writes it from a checked app name and its OWN day. `SendEndNotice` keeps no state and tries once: only `EndNoticeSent` tells the household; the daily limit (5 per household, counted in the sent log) answers `EndNoticeLimit` — the caller tries again, it never drops. **Every new entry needs its own ruling** — pinned by `TestD84_Receipt_OpensNothingElse`, `TestNotice_*`. |
| `store.NoteEndNotices` / `EndNotices` / `MarkEndNoticeTold` + `api.endNotices` (the notice lock, `07` §8.2f) | hub/internal/store/offsite_end_notice.go, hub/internal/api/end_notice.go | `NoteEndNotices(customerID, deployed, claims, tierOn, now)`; `EndNotices(customerID)`; `MarkEndNoticeTold(customerID, app, press, to, now)` | The hub's OWN record that a household (or the operator in its place) was told that an app's off-site copies will be deleted. `offsitekeys.agreeEnded` agrees only when it says „told” 30 days ago | **Written only by the hub, only after the mail service accepted the mail; never derived from the sent log or from a box's date.** `press` (the box's `removed_at`) is a key only: another value VOIDS the notice. An install, a take-back (a report that shows the tier ON and no record) and a household delete remove the row. A new condition of a deletion goes HERE, not into `notification_log`. |
| `store.NoteEndNotices` / `EndNotices` / `MarkEndNoticeTold` + `api.endNotices` (the notice lock, `07` §8.2f) | hub/internal/store/offsite_end_notice.go, hub/internal/api/end_notice.go | `NoteEndNotices(customerID, deployed, claims, tierOn, now)`; `EndNotices(customerID)`; `MarkEndNoticeTold(customerID, app, press, to, addrKey, now)`; `NoticeAddressKey(email)`; `ValidNoticeApp(app)` | The hub's OWN record that a household (or the operator in its place) was told that an app's off-site copies will be deleted. `offsitekeys.agreeEnded` agrees only when it says „told” 30 days ago | **Written only by the hub, only after the mail service accepted the mail; never derived from the sent log or from a box's date.** `press` (the box's `removed_at`) is a key only: another value VOIDS the notice. An install, a take-back (a report that shows the tier ON and no record) and a household delete remove the row. A new condition of a deletion goes HERE, not into `notification_log`. **Told to the household is told AT AN ADDRESS** (`told_addr`, a hash): the reader counts it only at the address on record now, and `SaveNotificationPrefsAs` un-tells on a change — a new writer of `customer_notifications.email` needs nothing more, the reader covers it. A name for a household's mail passes `ValidNoticeApp` (a plain slug, no dot). The `…ForTest` helpers refuse outside a test binary. |
| `Dispatcher.SendOperatorNow` | hub/internal/notify/end_notice.go | `SendOperatorNow(customerID, eventType, severity, message, detailsJSON) error` | An operator mail whose DELIVERY is a condition of something else: it answers only when the mail service has (nil = accepted) | Operator-only types only; no cooldown and no background retry — the caller keeps its own „told once” record and tries again, **and bounds itself** from the sent log (`store.CountOperatorTriesSince` — sent AND failed tries — and `OperatorSentAboutSince`: per household a day, per thing a week — `api.endNoticeToOperator`). For every other operator mail use `ProcessEvent`. |
| `accesslog.New` / `Middleware` / `Mark` (v0.158.0, R-1140) | hub/internal/accesslog/accesslog.go | `Mark(ctx, kind)` | The hub's own access log (`<data_dir>/access-log/`, 90 days) and marking the identity KIND an auth check established | Never log a value: the path only (no query; `/bind/<token>` and 32+-char segments redacted). A new auth path calls `Mark` with its kind. A logging failure never fails a request. |
| the timed SQLite driver `sqlite-timed` + `SetSlowStatementThreshold` (v0.178.0, R-1346) | hub/internal/store/timeddriver.go | `store.New` opens it — nothing to call | Names a statement over 1 s: `[WARN] slow statement: <ms> (over 1s): <SQL>` | The SQL text only, never a bound value. Put a heavy statement's SQL in a const and pin its plan (`r1346_speed.go`, `TestR1346_HeavyStatementsUseTheirIndex`): on the hub's network disk a whole-table read is seconds to minutes. |
@@ -1835,7 +1835,7 @@ minutes). **[FACT]** 9202 rc.6: an image that exits after 20 s → not started,
unit back → success, copy released 3 minutes later. Tester 1 on 0.343.0: a unit restore and a set-aside restore, each
„ran stably for 3m0s … the restore copy is released" (`audits/release-2026-10-26/`).
### 8.2f The off-site copies of a removed app end 30 days after „delete backup data” `[FACT — built, not released: controller `f628cb5` and hub `01a106b7` + `a63f5b2b` (after v0.182.0), 2026-11-15; the notice lock and the text changes: hub `42ef25c2`, `9ef8cee1`, `c9d67309` and controller `10df99b`, 2026-11-15 evening; NO box has run it]` (D72 and D84, `09` §3 decisions 292 and 309; the notice lock and the texts, decisions 315 and 316; R-1374 part 1; designed 2026-11-14)
### 8.2f The off-site copies of a removed app end 30 days after „delete backup data” `[FACT — built, not released: controller `f628cb5` and hub `01a106b7` + `a63f5b2b` (after v0.182.0), 2026-11-15; the notice lock and the text changes: hub `42ef25c2`, `9ef8cee1`, `c9d67309` and controller `10df99b`, 2026-11-15 evening; the independent review's six fixes: hub `73a534e7`, `508f936a`, `b391a232`, `cbfeeb62`, `a6f4aa0b`, `efea8382`, 2026-11-15 night; NO box has run it]` (D72 and D84, `09` §3 decisions 292 and 309; the notice lock and the texts, decisions 315 and 316; R-1374 part 1; designed 2026-11-14)
**The ruling.** When the household removes an app and presses „delete backup data” (`remove_backups`), that app's
off-site copies end 30 days later, at the next clean-up after that day — the number of a restore copy (D62). When the
@@ -1905,13 +1905,27 @@ The mail D84 promises was not a condition of the deletion. Now it is.
records (`offsite.ended_apps` — while the off-site tier is switched on). The hub keeps one row per (household,
app) such a report names (`offsite_end_notices`, `store.NoteEndNotices`) and, after each report, mails every row
that is not told (`api.endNotices` → `notify.SendEndNotice`) — at that report and at later ones until the mail
service accepts the mail. Only then does the row say „told”, with the hub's time. One row per press: one notice
service accepts the mail. Only then does the row say „told”, with the hub's time — read AFTER the send returned,
never the walk's start (review fix 4). One row per press: one notice
per press, however many reports name it. **The box's event mails nobody**; it is the operator's record only. So a
lost event, an event sent twice and an event that never comes all change nothing.
2. **The hub agrees only 30 days after the notice.** `offsitekeys.agreeEnded` now needs BOTH: the app absent from
the box's app list for 30 days by the hub's clock (as before), AND the hub's own row saying „told” at least 30
days ago by the hub's clock. No row, a row not told, a row told later: refused, and the window's answer names the
reason. The day in the mail is the hub's own — the day of the mail + 30 days, in Budapest time — not the box's.
2a. **„Told” is told AT AN ADDRESS (review fix 1 — the hole D84 exists for).** A person with the household's login
could set the notification address to his own, press, get the notice and put the real address back. So a row
told to the household keeps a key of the address the mail was accepted for (a hash; the address is not stored
twice), and it counts as told only while that is the address on record NOW. A save that changes the address,
removes it or adds a first one un-tells the household's rows; the next report mails the address the household
has, and the 30 days start again. The same address in other capitals or with spaces is the same; a push with an
empty address (the hub keeps the stored one) changes nothing. *This rule — „a changed address is told again and
waits again” — was built by CC on the review's finding, 2026-11-15; the operator may reverse it.* The other
option: the first notice stands whatever happens to the address (cost: the attack above works).
2b. **A name that reaches a household's mail is a plain app slug (review fix 3)** — lower-case letters, digits, `-`,
`_`, no dot, at most 64 (`store.ValidNoticeApp`; all 66 catalog names pass). A box could otherwise put
`www.some-bank.example.com` into the subject of the hub's mail. Any other name gets no row, no mail and is never
agreed.
3. **Where „told” is kept.** In the hub's own table, written only by the hub and only after the mail service
accepted the mail. Not derived from the sent log (`notification_log` — nothing prunes a living household's rows
today, but a condition of a deletion must not rest on a log), and never from a box's word. The box's `removed_at`
@@ -1921,7 +1935,8 @@ The mail D84 promises was not a condition of the deletion. Now it is.
run). Another press (another key) resets it. A new press needs a new notice and a new 30 days. A report that
does not show the tier (it is off) changes nothing: its silence is not a take-back.
5. **The limit per day delays; it never drops.** At most 5 notices per household in 24 hours, counted in the hub's
sent log; the sixth stays „not told” and goes at a later report.
sent log; the sixth stays „not told” and goes at a later report. The limit counts every try that reached the
mail service — sent AND failed: a send that timed out on the hub's side may have gone (review fix 2).
6. **A household with no address, or a blocked one — the operator is told in its place, and that starts the 30
days.** One mail per app (`offsite_end_notice_operator`, operator-only, sent with `SendOperatorNow`, which
answers only when the mail service has). When the household gets an address later, the hub mails the household
@@ -1933,8 +1948,8 @@ The mail D84 promises was not a condition of the deletion. Now it is.
counts when an address comes later (cost: a person who holds the login can remove the address, press, and put
the address back on day 29 — the household then reads „deleted tomorrow”).
7. **A notice that cannot go out** (the mail-hold marker, a send that fails, no mail service): nobody is told, the
row keeps the reason in the hub's own words, the next try is at a report at least one hour later, and nothing is
agreed. **After 3 days** without a notice the operator gets one line (`offsite_end_notice_stuck`, once per app, at
row keeps the reason in the hub's own words, the next try is at a report at least one hour later — then 2, 4,
8, 16 and 24 hours (review fix 2) — and nothing is agreed. **After 3 days** without a notice the operator gets one line (`offsite_end_notice_stuck`, once per app, at
most 5 per household a day, not while the mail hold is on). *Why 3 days:* it is longer than any outage of the
mail service the hub has had, longer than the hold on a restored copy is meant to last, and longer than the
daily limit delays an honest household (15 apps removed at once are all told inside it) — so the line means
@@ -1981,6 +1996,11 @@ and needs a test on a box with an older hub. Not built; named in the build's rep
| Seven apps removed in one day | Five notices that day, two the next; none is dropped | hub `TestNotice_TheDailyLimitDelaysAndNeverDrops` |
| Told 29 days ago; told, but absent for 10 days only | Refused: both 30 days are needed | hub `TestNotice_AgreeEnded_NoNoticeNoDeletion` |
| A box of a household with no address names presses without end | The operator gets at most 5 in-place notices a day for that household, the same app once in 7 days; the rest wait and are not told | hub `TestNotice_NoAddress_ABoxCannotFloodTheOperator` |
| Somebody with the login changes the address to his own, presses, and puts the real address back | The row is un-told at the save; the real address is mailed at the next report and the 30 days start again | hub `TestReview1_ToldDoesNotSurviveAnAddressChange`, `TestReview1_ToldCountsOnlyAtTheAddressOnRecord`, `TestReview1_Window_ToldAtAnotherAddressIsNotTold` |
| The address is changed back and forth; removed; changed while the mail is on its way; saved again unchanged | Told only when the newest notice went to the current address (5 mails a day at most); the operator is told in place; not told; nothing changes | hub `TestReview1_BackAndForth_Removed_AndDuringTheSend`, `TestReview1_ASaveThatChangesNothingKeepsTheNotice` |
| A send errors after the mail service accepted it (a client timeout) | At most 4 mails in 12 hours and 5 in a day; never „told”; the 3-day line still comes | hub `TestReview2_ASendThatErrorsAfterItWasAcceptedIsNotMailedEveryHour` |
| A box names an „app” that is a link-shaped word | No row, no mail, never agreed | hub `TestReview3_*` |
| A walk with many rows or a slow mail service | Each told time is read after its own send returned | hub `TestReview4_ToldIsTheTimeAfterTheSendReturned` |
| A box changes the press's key in every report | The notice is reset each time: the household gets at most 5 mails a day, and nothing is ever agreed | hub `TestNotice_Record_WhatVoidsIt`, `TestNotice_TheDailyLimitDelaysAndSurvivesARestart` |
| The box is off at the date, or the store cannot be reached | The next window that runs does it: the record does not age | `TestD72_EndRecord_Due` |
| The off-site tier is switched off at the date | No run, no window, no call to the store; the record stays | `TestD72_TierOffAtTheDate_TheRecordWaits` |
@@ -2051,9 +2071,21 @@ clock, and then name snapshots of other apps under it. What bounds that now, all
show „kept” and go on naming the app. The mail's last line then does not help; the operator does (the mail's
sign-off), by switching the weekly windows off for that household. **Open.**
- **A household with no address is not told; the operator is.** What happens next depends on the operator.
- **The address is the one on record at the mail.** A person who holds the login and changes the notification
address first gets the mail himself. Whether the old address is told of such a change was not checked in this
build. **Open.**
- **A changed address is told again** (review fix 1): the notice counts only for the address the household has
now. **NOT closed: a person who holds the login AND keeps the address changed** — or who also reads the
household's mailbox. He gets the mail, 30 days pass, the hub agrees. Nothing in the hub tells the OLD address that
the address was changed. `[DESIGN — proposed, not built]`: one mail to the old address when a household's
notification address changes or is removed („your Felhom notification address was changed; if this was not you
…”). It is a new household-facing mail and a new piece of kept personal data (the old address, for one mail), so
it needs the operator's ruling; a test on a box would show whether the box's save reaches the hub before the
intruder's next press.
- **Two reporters of one household void each other's notice** (the review's finding 5; not built). A controller's
report is accepted on the household's ONE key and stored by household only (`reports` has no column for a box;
`checkAuthCustomer`), and the hub's own comment says „a customer is expected to have at most one host”
(`store.GetHostByCustomer`). So two controllers are not a supported shape, and nothing prevents them: a cloned or
restored guest that keeps its `controller.yaml` reports as the same household. One names the press and the other
does not: the notice is made and voided in turn — the household gets up to 5 mails a day and nothing is ever
agreed (the safe direction, and noisy). **Open.**
- **Noise, not loss:** a box can make the hub mail its household 5 notices a day (by changing the press's key), and
the operator 5 in-place notices and 5 „stuck” lines a day per household. Nothing is agreed while it does.
@@ -471,7 +471,7 @@ own records. What that adds here:
| Event | Severity | Who | When |
|---|---|---|---|
| `offsite_end_scheduled` (from the box) | info | recorded, **mailed to nobody** (the notice lock, `09` §3 decision 315): the operator's record of the press | the household pressed „delete backup data” at a removal, or „delete in 30 days” on the restore page |
| the household's notice (hub; no event — logged in the sent log as `offsite_end_scheduled`) | — | **the household** — one mail per press to its own notification address, whatever its group switches say; never the operator (`notify.SendEndNotice`). Sent by the hub from the box's REPORT, at every report until the mail service accepts it; at most 5 per household in 24 hours (the rest go later) | a report first names the app in a pending end record. The hub agrees to the deletion no earlier than 30 days after this mail |
| the household's notice (hub; no event — logged in the sent log as `offsite_end_scheduled`) | — | **the household** — one mail per press to its own notification address, whatever its group switches say; never the operator (`notify.SendEndNotice`). Sent by the hub from the box's REPORT, at every report until the mail service accepts it; at most 5 per household in 24 hours (the rest go later) | a report first names the app in a pending end record — and again when the household's notification address changes (the notice counts only at the address the household has now). The hub agrees to the deletion no earlier than 30 days after this mail. A try that failed counts toward the 5 a day, and the wait between tries doubles (1 h … 24 h) |
| `offsite_end_notice_operator` (hub; decision 315) | warning, **mailed** (sent at once, the answer of the mail service is awaited) | operator-only, once per app; at most 5 per household in 24 hours, the same app once in 7 days | the household has no notification address, or is blocked: this mail is the notice in its place and starts the 30 days. An address added later: the household is mailed and the 30 days start again |
| `offsite_end_notice_stuck` (hub; decision 315) | warning, **mailed** | operator-only, once per app (details `subject`); at most 5 per household in 24 hours; not while the mail hold is on | a notice has told nobody for 3 days (the mail hold, a failing send, the daily limit). Nothing of that app is removed meanwhile |
| `offsite_ended_app_removed` (hub) | info | operator-only, recorded, not mailed | a window removed an app's agreed snapshots — one per app, with the count |