Repository navigation
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 intoSep 29, 2026
Conversation
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
marked this pull request as ready for review
September 29, 2026 06:31
cofade
deleted the
fix/230-233-246-235-readmodel-delete-errors-hygiene
branch
September 29, 2026 06:31
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.
ModuleReadModelattributes fan-out failures per leg (failedLegs, leg names in the new contractsDataLegunion). A dead/modulesleg answers 503 plusRetry-After: 5with{ 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 intoX-Highfive-Data-Incompletein 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 (newcommon.dataIncomplete,dashboard.storeUnavailable*keys; the deadheartbeatDataIncompletekey is gone from both locales).#233 — deletes are atomic-observable and cascade fully.
DELETE /modules/<id>clears all seven tables (nest_detectionsincluded) 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_moduleuses a compensating snapshot/restore dance under the global lock, NOTwrite_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 reasonset_display_namedances too.delete_image_uploadDOES usewrite_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,HTTPExceptionpassthrough; every per-routestr(e)wrapper removed (grep-verified)._to_intdegrades non-finite values to NULL (INT32-clamped, documented);add_progressanswers 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 toquery_allwith canonicalised ids;_canonicalize_or_400deduplicated intoroutes/_module_id.py.#235 — public-wire hygiene.
emailleaves the publicModulewire (contracts, backend mapping, AdminPage column — nothing populated it; the stored column and firmware-sent value are unchanged). Both Flask services passuse_debugger=False; every documented dev.envnow saysDEBUG=false. Waitlist relay sendsallowed_mentions: { parse: [] }.Follow-ups filed separately: #283 (write-only email column residue), #284 (image-service
list_imagesstr(e), same leak class, duckdb-out-of-scope).Gates (actual numbers)
npm run typecheckclean (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.tests/e2e/, own compose stack): 6 passed. UI (tests/ui, real Chromium, own stack): 16 passed, plus the 2 newdashboard-degradedspecs green (page.route interception: partial header + 503).pio test -e native— nogccon this Windows host (environment gap); zero firmware files touched.Live run (dev compose stack)
Healthy: 200 with 7 seeded modules, no
emailkey on the wire. With duckdb-service stopped: 503 +{"error":"upstream module store unavailable"}+Retry-After: 5on list AND detail. On restart: immediate 200 (no stuck cache). Heartbeatrssi=1e400andbattery=-inf: both 200{"ok": true}. LiveDELETE /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
gh pr checks <N> --watch --fail-fastgreen on CI (esp. the ui job, which reruns the two new specs on Linux Chromium).Deliberately left out
_to_intper-column widths (INT32 ceiling documented at the helper; every target column accepts it).No
productionpromotion and noSEQUENCEbump in this package — no firmware changes, nothing to ship to the fleet.