ai-note.md: follow-up decisions (cloud alert, negative lists, key names)

This commit is contained in:
ai-bot committed 2026-10-02 09:12:27 +00:00
1 parent 5db43f97eb
commit 5f0456dde9
1 file changed
+19 -8
+19 -8
View File
@@ -4,6 +4,8 @@
The requirements in section 19 of `TODO.md` are **implemented and verified**. The full test suite passes (60 tests, run by the user with `python3 -m unittest discover -s tests`). Section 19 of `TODO.md` and the items that section 19 changed in sections 4, 5, 6, 7, 9, 11 and 18 are ticked. The requirements in section 19 of `TODO.md` are **implemented and verified**. The full test suite passes (60 tests, run by the user with `python3 -m unittest discover -s tests`). Section 19 of `TODO.md` and the items that section 19 changed in sections 4, 5, 6, 7, 9, 11 and 18 are ticked.
A follow-up round of questions was then answered by the user; see "Decisions of the follow-up round". The cloud provider alert from that round is implemented, and 62 tests pass.
Treat section 19 as authoritative wherever older requirements elsewhere in `TODO.md` conflict with it. Do not re-open the decisions below; they are settled and built. Treat section 19 as authoritative wherever older requirements elsewhere in `TODO.md` conflict with it. Do not re-open the decisions below; they are settled and built.
**Do not edit `TODO.md` outside section 19 without asking the user.** Section 8 is still stale; see "Remaining work" at the end of this note. **Do not edit `TODO.md` outside section 19 without asking the user.** Section 8 is still stale; see "Remaining work" at the end of this note.
@@ -41,12 +43,24 @@ These were settled in a question-by-question review. Do not re-open them.
7. **OK / Problem is mandatory for the two verification fields.** There is no "not assessed" option and an empty value is rejected at save. They are required only when the key is available, per decision 8. 7. **OK / Problem is mandatory for the two verification fields.** There is no "not assessed" option and an empty value is rejected at save. They are required only when the key is available, per decision 8.
8. **Unavailable key.** When `available = No`, the remaining key fields (hardware works, firmware version, seed backup, address path) are hidden and not required. The key note stays available, for example to record why the key is missing or that a replacement has been ordered. The only alert in this case is the critical one: *"This key was not available. Replace the key before continuing; the remaining checks for this key cannot be recorded."* The app must not raise a seed-backup or address alert for an unavailable key, because those checks could not be performed. 8. **Unavailable key.** When `available = No`, the remaining key fields (hardware works, firmware version, seed backup, address path) are hidden and not required. The key note stays available, for example to record why the key is missing or that a replacement has been ordered. The only alert in this case is the critical one: *"This key was not available. Replace the key before continuing; the remaining checks for this key could not be recorded."* The app must not raise a seed-backup or address alert for an unavailable key, because those checks could not be performed.
9. **Legacy records stay readable.** Existing multi-key records must keep rendering in the history. The migration must map old boolean flags to the new status values (`1` → `OK`, `0` → `Problem`) and fold the old `seed_backup_status` into `seed_backup_verified`. 9. **Legacy records stay readable.** Existing multi-key records must keep rendering in the history. The migration must map old boolean flags to the new status values (`1` → `OK`, `0` → `Problem`) and fold the old `seed_backup_status` into `seed_backup_verified`.
--- ---
## Decisions of the follow-up round
Settled after section 19 was implemented and verified.
10. **A negative cloud result is a critical alert.** `cloud_health_status = PROBLEM` or `cloud_provider_operational = 0` on the cloud key raises the new critical alert `cloud_provider_problem`: *"The cloud provider is not operating normally. Check the provider status before continuing."* It is implemented in `alerts.py`, documented in section 7 of `TODO.md` and in `README.md`, and covered by two tests in `tests/test_alerts.py`. It is suppressed for an unavailable key, like the other key-level alerts.
11. **The two negative requirement lists stay unticked.** The "Dette skal ikkje vere med i første versjon" list in section 1 and the "Unngå" list in section 13 are standing prohibitions, not tasks, so they are never ticked. A note in each section says they must be confirmed again before release.
12. **Readable user-defined key names are not built.** Section 3 keeps its item unticked. The three fixed names are enough for the MVP; the database and `seed_fixed_keys` already preserve a custom name if one is ever set.
---
## How it was implemented ## How it was implemented
Schema version 5. All application code is Python's standard library plus vanilla JavaScript; no new dependencies. Schema version 5. All application code is Python's standard library plus vanilla JavaScript; no new dependencies.
@@ -54,7 +68,7 @@ Schema version 5. All application code is Python's standard library plus vanilla
- `database.py` — `SCHEMA_VERSION = 5`. New columns `health_checks.wallet_software` and `health_checks.software_version` (the legacy `sparrow_version` and `nunchuk_version` columns stay). `key_checks` now stores `seed_backup_verified` and `address_path_verified` as `OK`/`PROBLEM` and no longer has `seed_backup_status`, `address_verified`, or `derivation_height`. `ai_security_checks` accepts only the four English values. Two explicit, idempotent rebuilds run inside the existing `BEGIN IMMEDIATE` transaction: `_migrate_key_checks` and `_migrate_ai_security_checks`. Each detects the old layout (legacy column names, or a `CREATE TABLE` statement without `SECURE`) and copies every row with a value mapping. `tool_checks` keeps its `version`, `checked_at`, and `notes` columns for legacy rows but no longer writes them. - `database.py` — `SCHEMA_VERSION = 5`. New columns `health_checks.wallet_software` and `health_checks.software_version` (the legacy `sparrow_version` and `nunchuk_version` columns stay). `key_checks` now stores `seed_backup_verified` and `address_path_verified` as `OK`/`PROBLEM` and no longer has `seed_backup_status`, `address_verified`, or `derivation_height`. `ai_security_checks` accepts only the four English values. Two explicit, idempotent rebuilds run inside the existing `BEGIN IMMEDIATE` transaction: `_migrate_key_checks` and `_migrate_ai_security_checks`. Each detects the old layout (legacy column names, or a `CREATE TABLE` statement without `SECURE`) and copies every row with a value mapping. `tool_checks` keeps its `version`, `checked_at`, and `notes` columns for legacy rows but no longer writes them.
- `validation.py` — `validate_health_check(payload, keys)` now takes the key profiles instead of key ids, and normalizes one `key_check` object. `next_check_due()` is a module-level helper that adds one calendar year and clamps 29 February to 28 February; the payload's `next_check_due` is ignored. Irrelevant products and providers, duplicate rows, unknown keys, a non-Nunchuk software choice for key 3, and a missing verification status for an available key are all rejected. - `validation.py` — `validate_health_check(payload, keys)` now takes the key profiles instead of key ids, and normalizes one `key_check` object. `next_check_due()` is a module-level helper that adds one calendar year and clamps 29 February to 28 February; the payload's `next_check_due` is ignored. Irrelevant products and providers, duplicate rows, unknown keys, a non-Nunchuk software choice for key 3, and a missing verification status for an available key are all rejected.
- `app.py` — passes `list_keys(...)` to the validator. No other routing change. - `app.py` — passes `list_keys(...)` to the validator. No other routing change.
- `alerts.py` — `seed_backup_problem` reads `seed_backup_verified`, `address_verification_failed` reads `address_path_verified`, the security statuses are English, and an unavailable key returns only the single critical `key_unavailable` alert. - `alerts.py` — `seed_backup_problem` reads `seed_backup_verified`, `address_verification_failed` reads `address_path_verified`, `cloud_provider_problem` reads `cloud_health_status` and `cloud_provider_operational`, the security statuses are English, and an unavailable key returns only the single critical `key_unavailable` alert.
- `static/health-check.html`, `static/health-check.js` — the form selects one key and one wallet software, renders the key, BIP327/SLIP39 and security fields for that selection, hides the key fields when the key is unavailable, and shows the derived next check date as read-only text. - `static/health-check.html`, `static/health-check.js` — the form selects one key and one wallet software, renders the key, BIP327/SLIP39 and security fields for that selection, hides the key fields when the key is unavailable, and shows the derived next check date as read-only text.
- `static/history.js` — the detail view shows the checked key and the software selection; the legacy version columns are rendered only when an old record actually has them. - `static/history.js` — the detail view shows the checked key and the software selection; the legacy version columns are rendered only when an old record actually has them.
- `README.md` — documents the per-key POST contract, the alert rules, and the migration. - `README.md` — documents the per-key POST contract, the alert rules, and the migration.
@@ -84,7 +98,7 @@ Two implementation choices worth knowing:
These were the open items with a stated default; the defaults were implemented. These were the open items with a stated default; the defaults were implemented.
- `hardware_works` and `firmware_version` for keys 1 and 2: not required. - `hardware_works` and `firmware_version` for keys 1 and 2: not required.
- `cloud_health_status` and `cloud_provider_operational` for key 3: not required. - `cloud_health_status` and `cloud_provider_operational` for key 3: not required. A negative value does raise the critical alert from decision 10.
- `contact_info_verified`: optional, with a "not assessed" choice. - `contact_info_verified`: optional, with a "not assessed" choice.
- New column names for the software choice: `wallet_software` and `software_version` on `health_checks`, while the legacy `sparrow_version` and `nunchuk_version` columns stay for old rows. - New column names for the software choice: `wallet_software` and `software_version` on `health_checks`, while the legacy `sparrow_version` and `nunchuk_version` columns stay for old rows.
@@ -109,12 +123,9 @@ The migration touches four tables, and it is the riskiest part of the change:
- **Step 8 — `GET /api/export`.** CSV with clear Excel documentation is the simple route; XLSX only if it is genuinely simple. - **Step 8 — `GET /api/export`.** CSV with clear Excel documentation is the simple route; XLSX only if it is genuinely simple.
- **Steps 9–12.** StartOS package (`startos/manifest`, `main.ts`, `interfaces.ts`, `backups.ts`, `init/`, `instructions.md`, `icon.svg`, `Makefile`), persistent volume, backup/restore, restart testing, and the final `.s9pk`. - **Steps 9–12.** StartOS package (`startos/manifest`, `main.ts`, `interfaces.ts`, `backups.ts`, `init/`, `instructions.md`, `icon.svg`, `Makefile`), persistent volume, backup/restore, restart testing, and the final `.s9pk`.
### Open questions that the user has not decided ### Still not in the specification
- `cloud_health_status = PROBLEM` and `cloud_provider_operational = 0` raise no alert, because section 7 does not list them. - `/api/alerts` is an extra endpoint that is not in the minimum list in section 11. It is described in `README.md` and noted in `TODO.md` section 11, but the specification itself has not been extended.
- The "Dette skal ikkje vere med" list in section 1 and the "Unngå" list in section 13 are still unticked. Every item is true today, but the user has not decided whether they count as "confirmed not built".
- Readable user-defined key names (section 3) are still not implemented.
- `/api/alerts` is an extra endpoint that is not in the minimum list in section 11. It is described in `README.md` but has not been added to the specification.
--- ---