Skip to content

fix: surface read-model outages, atomic deletes, uniform errors, wire hygiene (closes #230, closes #233, closes #235, closes #246) - #285

Merged
cofade merged 3 commits into
mainfrom
fix/230-233-246-235-readmodel-delete-errors-hygiene
Sep 29, 2026
Merged

cofade merged 3 commits into
mainfrom
fix/230-233-246-235-readmodel-delete-errors-hygiene

Conversation

@cofade

@cofade cofade commented Sep 25, 2026

Copy link
Copy Markdown
Collaborator

Package branch delivering four audit findings as one reviewable unit: backend/duckdb read-model truthfulness, delete atomicity and cascades, a uniform error envelope, and public-wire hygiene. Three senior-review rounds, all clean (no P0 in any round).

What shipped, per issue

#230 — read-model partial failure surfaces the outage.
ModuleReadModel attributes fan-out failures per leg (failedLegs, leg names in the new contracts DataLeg union). A dead /modules leg answers 503 plus Retry-After: 5 with { error: 'upstream module store unavailable' } on both the listing and the detail route (a detail 404 would assert a module does not exist); any other failed legs join into X-Highfive-Data-Incomplete in stable order (nests,progress,heartbeats, heartbeats-only byte-identical to before). Degraded snapshots are still never cached. The dashboard renders one banner naming the stale legs and an explicit 503 state with retry, in both locales (new common.dataIncomplete, dashboard.storeUnavailable* keys; the dead heartbeatDataIncomplete key is gone from both locales).

#233 — deletes are atomic-observable and cascade fully.
DELETE /modules/<id> clears all seven tables (nest_detections included) for both id forms; DELETE /image_uploads/<filename> clears that capture's detections; DELETE /images/<filename> unlinks source JPEG plus sidecar plus grammar-matched snips, row first then files.

Deviation from the issue letter, verified empirically (see evidence below): delete_module uses a compensating snapshot/restore dance under the global lock, NOT write_transaction(). Same-transaction child-then-parent DELETEs trip DuckDB 1.4.4 FK over-enforcement (ConstraintException) even in strict reverse-FK order, and no FK-disable pragma exists on this version — the reason set_display_name dances too. delete_image_upload DOES use write_transaction() per the issue (no FK edges between those two tables). The operator sees deleted / untouched-plus-500 / restore-failed-marker, never a silent half-delete. Residual window: process death between partial delete and in-memory restore (documented in the docstring, backup pointer in the delete-flow docs).

#246 — one JSON error envelope duckdb-side.
Single @app.errorhandler(Exception): generic 500, detail to the ring, HTTPException passthrough; every per-route str(e) wrapper removed (grep-verified). _to_int degrades non-finite values to NULL (INT32-clamped, documented); add_progress answers 400 on empty per-type dicts (validated before the transaction, so a 400 can never commit a partial write) and 404 on unknown modules; heartbeat/silence reads moved to query_all with canonicalised ids; _canonicalize_or_400 deduplicated into routes/_module_id.py.

#235 — public-wire hygiene.
email leaves the public Module wire (contracts, backend mapping, AdminPage column — nothing populated it; the stored column and firmware-sent value are unchanged). Both Flask services pass use_debugger=False; every documented dev .env now says DEBUG=false. Waitlist relay sends allowed_mentions: { parse: [] }.

Follow-ups filed separately: #283 (write-only email column residue), #284 (image-service list_images str(e), same leak class, duckdb-out-of-scope).

Gates (actual numbers)

  • backend vitest: 317 passed (35 files). homepage vitest: 206 passed (33 files + api round-trip). duckdb-service pytest: 322 passed. image-service pytest: 185 passed.
  • npm run typecheck clean (contracts/backend/homepage). npm run lint: 0 errors (63 pre-existing warnings). bash scripts/ruff.sh check + format --check: clean. make check-citations: 7 OK / 0 problems. check-agent-context: OK. Twin/bind/version/key guards in pre-push: all OK.
  • e2e (tests/e2e/, own compose stack): 6 passed. UI (tests/ui, real Chromium, own stack): 16 passed, plus the 2 new dashboard-degraded specs green (page.route interception: partial header + 503).
  • NOT run: pio test -e native — no gcc on this Windows host (environment gap); zero firmware files touched.

Live run (dev compose stack)

Healthy: 200 with 7 seeded modules, no email key on the wire. With duckdb-service stopped: 503 + {"error":"upstream module store unavailable"} + Retry-After: 5 on list AND detail. On restart: immediate 200 (no stuck cache). Heartbeat rssi=1e400 and battery=-inf: both 200 {"ok": true}. Live DELETE /modules/<id>: 200, row gone. No surprises beyond what the tests pin; nothing new for chapter 11 from the run itself.

Manual tests for the owner

  1. Dashboard degraded banner: stop duckdb-service, open the dashboard, confirm the unavailable panel with retry; restart, confirm it clears without refresh tricks. Pass = panel copy matches, no console errors. Failure = generic backend-down panel or stale banner (would mean the header/state wiring regressed).
  2. Admin delete on a module WITH images/detections: confirm sidecars/snips/detection rows are gone from disk/DB and unrelated captures survive. (Covered by tests; this is the production-data sanity check.)
  3. gh pr checks <N> --watch --fail-fast green on CI (esp. the ui job, which reruns the two new specs on Linux Chromium).

Deliberately left out

No production promotion and no SEQUENCE bump in this package — no firmware changes, nothing to ship to the fleet.

review added 3 commits September 26, 2026 00:10
… hygiene (closes #230, closes #233, closes #235, closes #246)

Package: backend/duckdb read-model truthfulness, delete atomicity and cascades, uniform error envelope, public-wire hygiene.

For #230 the read model attributes fan-out failures per leg (contracts DataLeg): a dead /modules leg answers 503 plus Retry-After on both listing and detail routes, other legs join into X-Highfive-Data-Incomplete in stable order, and the dashboard names the stale legs in one banner with an explicit 503 state.

For #233 deletes cascade fully (nest_detections on both duckdb deletes; sidecar plus grammar-matched snips on image-service deletes, row first then files). delete_module uses a compensating snapshot/restore dance, not write_transaction: same-transaction child-then-parent DELETEs trip DuckDB 1.4.4 FK over-enforcement even in strict reverse-FK order (ConstraintException, verified on :memory: 1.4.4; no FK-disable pragma exists), the reason set_display_name dances too. delete_image_upload does use write_transaction (no FK edges there).

For #246 one app-level JSON errorhandler (generic 500, detail to the ring, HTTPException passthrough) replaces every per-route str(e) wrapper; heartbeat parsing degrades non-finite values to NULL; add_progress answers 400/404 on empty-dict/unknown-module; reads go through query_all with canonicalised ids.

For #235 operator email leaves the public Module wire (contracts, backend, AdminPage column), both Flask services pass use_debugger=False, the waitlist relay sends allowed_mentions parse:[], and every documented dev .env now says DEBUG=false.

Follow-ups filed separately: #283 (write-only email column residue), #284 (image-service list_images str(e)). Deliberately out of scope: AdminPage 503 state (spec scoped to dashboard), _to_int per-column widths (INT32 ceiling documented), Playwright spec for deleting (covered at pytest layer).
…ier pass

The package commit's prettier pass padded a markdown table in the .claude mirror only, breaking the check-agent-context gate. Mirrors the formatted table into .agents. No content change.
…lacement

Senior review P2 fixes: the check_silence comment claimed single-threadedness makes the read/write split safe, but that only prevents concurrent check_silence runs — the real mitigations are the millisecond window and per-tick self-correction. Also moved the displaced 'Firmware-reported name' comment back onto the name field in the contracts Module interface.
@cofade
cofade marked this pull request as ready for review September 29, 2026 06:31
@cofade
cofade merged commit e30c341 into main Sep 29, 2026
23 checks passed
@cofade
cofade deleted the fix/230-233-246-235-readmodel-delete-errors-hygiene branch September 29, 2026 06:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant