pluriwave/openspec/changes/archive/2026-07-11-persistence-corruption-guard/archive-report.md

Archive Report: Persistence Corruption Guard

Change: persistence-corruption-guard Archived: 2026-07-11 Status: ARCHIVED AND CLOSED (see Archive Integrity note — folder deletion pending, content fully preserved) Archive Path: openspec/changes/archive/2026-07-11-persistence-corruption-guard/ Spec Merged To: openspec/specs/persistence-resilience/spec.md (new capability domain)

---

Executive Summary

The persistence-corruption-guard change is now archived with a PASS WITH WARNINGS verification verdict (0 CRITICAL, 2 WARNING, 4 SUGGESTION at verify time). It closes the highest-severity class from the 2026-07-11 full-app silent-failure audit (CRITICAL-1 + CRITICAL-4): a corrupt or schema-incompatible persistence read was silently coerced to an empty state, and the next write then committed that empty state to disk — permanently destroying user data with zero signal. Alarms was the worst instance: recalcularTodas() auto-persists on cold start and every 60 seconds with no user action, so a single bad read could erase all alarms automatically. The fix applies one shared architecture (per-entry tolerant parsing, skip-never-fabricate identity, degraded-read write suppression) across three subsystems — alarms, custom radio stations, and EQ presets/device names — shipped as three independently-revertible stacked commits. All 60 code-completable tasks are done (61 total; the sole remaining item, D4, is an explicitly optional on-device sanity check with no functional gap). 62/62 targeted tests pass, flutter analyze reports 0 issues, and WARNING W1 (a narrow uncaught-exception path introduced in estado_radio.dart) was fixed by the orchestrator after verification, with a RED-GREEN regression test added and a 53/53 re-run of the affected suites. WARNING W2 (a documentation-only gap in the multi-batch apply-progress evidence table) is accepted as non-blocking.

---

Artifact Traceability

Artifact	Engram Observation ID	Location	Notes
Explore	(embedded, no separate observation)	sdd/persistence-corruption-guard/explore.md on-disk only	Root-cause audit trace across 3 subsystems, shared defect architecture
Proposal	#2350	sdd/persistence-corruption-guard/proposal	Intent, scope (alarms/stations/EQ), shared 3-part fix approach, risks, rollback
Spec	#2351	sdd/persistence-corruption-guard/spec; merged to openspec/specs/persistence-resilience/spec.md	5 requirement groups, 10 scenarios; new persistence-resilience capability domain
Design	#2354	sdd/persistence-corruption-guard/design	6 architecture decisions (D1-D6), degraded-flag/write-authority matrix, file changes, testing strategy
Tasks	#2359	sdd/persistence-corruption-guard/tasks	61 checkboxes across Phases A-D; review workload forecast + stacked-to-main work-unit plan
Apply-Progress	#2360	sdd/persistence-corruption-guard/apply-progress	3 batches (Phase A, Phase B, Phase C+D) merged; 57/57 code tasks + 3/4 Phase D tasks complete
Verify-Report	#2363	sdd/persistence-corruption-guard/verify-report	PASS WITH WARNINGS; 10/10 spec scenarios independently re-verified compliant; W1/W2 findings

---

Implementation Completion

Phase A: Alarms (work unit 1, worst blast radius) — COMPLETE

Phase	Description	Tasks	Status	Evidence
A	Shared tolerant-parse helper (persistencia_tolerante.dart) + ServicioAlarmas per-entry tolerant parse + _lecturaAlarmasDegradada guard on recalcularTodas/_guardar	A1-A23 (23)	23/23 [x]	19/19 targeted alarms suite green; flutter analyze clean; commit 65c1ac2

Phase B: Custom Stations (work unit 2) — COMPLETE

Phase	Description	Tasks	Status	Evidence
B	EstadoRadio._cargarEmisorasCustom parse-vs-IO split, .corrupt sidecar quarantine, _customDegradado guard on _guardarEmisorasCustom	B1-B17 (17)	17/17 [x]	18/18 estado_radio_test.dart green (13 pre-existing + 5 new); flutter analyze clean; commit 13ad736

Phase C: Equalizer (work unit 3) — COMPLETE

Phase	Description	Tasks	Status	Evidence
C	4 ServicioEcualizador readers converted to parseMapaTolerante, principal-preset skip logging, no flag/quarantine (explicit-only, low recovery value)	C1-C17 (17)	17/17 [x]	25/25 servicio_ecualizador_test.dart green (20 pre-existing + 5 new); flutter analyze clean; commit 45b7fc8

Phase D: Final Sweep — 3/4 COMPLETE (D4 optional, non-blocking)

Phase	Description	Tasks	Status	Notes
D	Whole-project flutter analyze + targeted 7-file cross-phase test sweep; optional on-device sanity check	D1-D4 (4)	3/4 [x]	D1/D2/D3 done (0 issues, 62/62 pass, hang-avoidance documented); D4 explicitly optional — no device/emulator available in this environment, every behavior already Dart-testable and covered

Task Summary: 60 tasks complete ([x]), 1 task intentionally left [ ] with an explicit skip rationale (D4). Total: 61 checkboxes, 0 unaccounted.

---

Test Results

Unit Tests (independently re-executed at verify time, not trusted from self-report)

Suite	Tests	Result	Notes
persistencia_tolerante_test.dart	5/5	PASS	New file — shared helper unit tests
servicio_alarmas_corrupcion_test.dart	4/4	PASS	New file — alarms corruption/degraded-guard cases
servicio_alarmas_cache_test.dart, servicio_alarmas_proxima_test.dart, servicio_alarmas_snooze_test.dart	included in 19/19	PASS	Pre-existing, unmodified, regression-locked
estado_radio_test.dart	18/18	PASS	13 pre-existing + 5 new
servicio_ecualizador_test.dart	25/25	PASS	20 pre-existing + 5 new
Total (targeted 7-file gate)	62/62	PASS	Matches apply-progress D2 claim exactly, independently reproduced at verify time

Static Analysis

Tool	Result	Coverage
flutter analyze	0 issues	Whole project, independently reproduced at verify time

Coverage

• flutter test --coverage was launched as a background/informational check; did not complete within the verification report-writing window. Not blocking — Strict TDD treats coverage as informational only. Correctness is established by the pass/fail gate above plus direct source-diff inspection.

---

Verification Summary

Verdict

PASS WITH WARNINGS — 0 CRITICAL, 2 WARNING, 4 SUGGESTION at verify time.

All 10/10 spec scenarios independently verified compliant with named, re-executed passing tests. All 6 design decisions (D1-D6) verified against actual source diffs via git show, not self-reported summaries alone. 62/62 targeted tests and 0 flutter analyze issues independently reproduced. 60/61 tasks complete, with the sole incomplete task (D4) explicitly optional and non-blocking.

WARNING Resolution (post-verify, before archive)

Finding	Severity	Status at Archive
W1 — _archivoCustom() path resolution left outside the IO try/catch in estado_radio.dart; a hypothetical path_provider resolution failure would throw uncaught into EstadoRadio._init()'s Future.wait(...), also affecting sibling loads (cargarPopulares/cargarFavoritos/cargarGruposFavoritos)	WARNING	CLOSED. Fixed by the orchestrator post-verify (commit 316e9a7/48e74e6): _archivoCustom() is now called inside its own try/catch in _cargarEmisorasCustom(), setting _customDegradado=true and logging via registrarSaltoPersistencia on failure instead of throwing. A RED-GREEN regression test was added. Targeted gate re-run: 53/53 green across the 4 persistence suites touched. Independently confirmed present in source at archive time via direct read of lib/estado/estado_radio.dart.
W2 — Multi-batch apply-progress "TDD Cycle Evidence" table only carries a row for the final batch (Phase C); Phase A/B evidence lives inline in tasks.md instead of a consolidated table, likely lost on topic_key upsert across the 3 apply-progress save revisions	WARNING	ACCEPTED-DOCUMENTED, non-blocking. Not a RED/GREEN discipline failure — independently corroborated via source-diff inspection and the full regression re-run. Flagged as a process/tooling gap: future multi-batch changes should concatenate TDD Cycle Evidence rows across batches rather than keeping only the latest. No code or spec impact.

Compliance Matrix Snapshot

Requirement	Scenarios	Compliant	Notes
Per-entry tolerant parsing preserves valid siblings	3	3	alarms, stations, EQ maps
Entry identity is never fabricated	2	2	alarms (no id), stations (no uuid)
Degraded read suppresses automatic writes / restores on authority	3	3	alarms (flag), stations (parse-vs-IO split, see Note A), EQ (no flag, explicit-only, see Note B)
Healthy reads are behaviorally unchanged	1	1	full 62/62 regression re-run
Diagnostics are developer-facing only, no l10n	1	1	log-assertion tests + zero l10n file changes across all commits
Total	10	10	0 deferred, 0 N/A, 0 untested

Note A: design D5 splits stations' total-corruption into a parse-fail path (flag-free, restores immediately on the next explicit add/remove) and an IO-fail path (_customDegradado deliberately NOT lifted by an explicit mutation — only a subsequent clean/partial load clears it, to avoid clobbering a possibly-intact file). This narrows the spec's general "user intent wins" prose for that one sub-case without contradicting the written scenario (flagged as SUGGESTION S2 for a spec-wording fast-follow, non-blocking).

Note B: EQ has no automatic writer at all, so "no automatic write while degraded" is true by construction in both old and new code — this half of the EQ scenario is structurally vacuous (mirrors Phase A's own A12 precedent); the test's real value is proving the explicit-write-after-total-corruption round-trip still works (SUGGESTION S3, non-blocking).

---

File Changes Summary

Estimated Changed Lines: ~1057 total across 3 stacked work-unit commits (Alarms 514, Stations 312, EQ 231), plus a small post-verify W1 fix commit. 400-Line Budget Risk: High (forecasted and mitigated by the tasks-phase stacked-to-main chain plan — Alarms → Stations → EQ, each independently shippable and revertible). Build Execution: Not run (flutter build explicitly excluded per repo convention — known unrelated full-build/full-suite hang risk).

New Files

• lib/servicios/persistencia_tolerante.dart — shared parseListaTolerante<T>, parseMapaTolerante<V>, registrarSaltoPersistencia() (D1)
• test/servicios/persistencia_tolerante_test.dart (5 tests)
• test/servicios/servicio_alarmas_corrupcion_test.dart (4 tests)

Modified Files

• lib/servicios/servicio_alarmas.dart — tolerant _parsear, _cacheRaw normalization on partial load (D3), _lecturaAlarmasDegradada guard on recalcularTodas/_guardar (D4)
• lib/modelos/alarma_musical.dart — doc comment only, zero functional change (D2: caller hardens, model unchanged)
• lib/estado/estado_radio.dart — parse-vs-IO split, .corrupt sidecar quarantine, _customDegradado guard (D5); post-verify W1 fix wraps _archivoCustom() resolution in the same IO-fail treatment
• lib/servicios/servicio_ecualizador.dart — 4 readers converted to parseMapaTolerante, principal-preset skip logging (D6, no flag/quarantine)
• test/estado/estado_radio_test.dart — +5 tests, _ArchivoEspia spy, _crearArchivoCustomRaw helper, W1 regression test
• test/servicios/servicio_ecualizador_test.dart — +5 tests, debugPrint capture harness

Localization

• lib/l10n/*.arb: 0 changes — confirmed via git show --stat on all commits; this capability is diagnostics-only, developer-facing, no user-visible copy.

---

Deviations from Design

Documented and accepted, no design violation:

1. B8 (Phase B, Stations IO-fail split): _archivoCustom()'s own path resolution was initially called BEFORE the new _leerContenidoCustom try block, matching the task's literal scope ("read archivo.readAsString() in its own try"). This was self-disclosed by the apply agent as WARNING-worthy and confirmed as W1 at verify time; closed post-verify (see WARNING Resolution above).
2. C10 (Phase C, _leerPresetsPorEmisora): no dedicated new corruption test targets this method directly — its correctness rests on being byte-for-byte the same conversion shape as _leerMapa (directly tested by C2/C3) plus the shared helper's own exhaustive unit tests. Flagged and accepted as SUGGESTION S1, non-blocking.
3. C4 / A12 (vacuous-RED characterization tests): EQ never had a write-suppression flag in either the old or new code, so "explicit write still succeeds after total corruption" cannot be made RED by construction for EQ. This is intentional regression-lock engineering against ever accidentally adding a flag to EQ (which would violate D6's explicit-only design), not a rigor gap. Accepted as SUGGESTION S3, non-blocking.

---

Risks and Mitigations

Risk	Likelihood	Status
Guard suppresses legitimate recalcularTodas writes	Med	Mitigated — flag triggers ONLY on a failed last read; existing recalc tests lock normal behavior; no-thrash independently verified with a real write-counting test
_cacheRaw normalizing rewrite loses survivor data	Low	Mitigated — non-destructive, logged, surviving valid entries only; verified via source-diff
EQ matrix key round-trip breakage (colon-delimited station:device keys)	Low	Mitigated — explicit round-trip tests including a MAC-style multi-colon key survivor case
Flag lifecycle leaks across sessions	Low	Mitigated — in-memory per instance, cleared on success/mutation (asymmetric for stations IO-fail by design, D5)
_archivoCustom() path-resolution failure escapes uncaught (W1)	Low probability, real if triggered	CLOSED — fixed post-verify, RED-GREEN regression test added

---

Next Steps

Recommended, Non-Blocking

1. S1: add a dedicated corruption test for _leerPresetsPorEmisora (EQ per-station presets) for defense-in-depth, even though residual risk is already very low.
2. S2: fast-follow the spec text for Requirement 3 ("degraded top-level read suppresses automatic writes until authority is restored") to explicitly distinguish the decode/parse-failure sub-case (authority restorable by explicit mutation) from the IO/read-failure sub-case (D5's deliberately stricter, non-restorable-by-mutation station behavior), so a reader of the spec alone is not surprised by the asymmetry.
3. S4: none required — cardinality mismatch between spec wording (3 valid + 1 malformed) and covering tests (2 valid + 1 malformed) is behaviorally equivalent and non-blocking.
4. W2 process fix: when merging multi-batch apply-progress under one topic_key, concatenate each batch's TDD Cycle Evidence rows instead of keeping only the latest batch.

Follow-Up Opportunities (Out of Scope for This Change)

• EQ/alarms total-corruption on an explicit mutation still forfeits the unreadable blob (accepted per the user-intent rule in the proposal). A symmetric SP _corrupto backup-key quarantine for alarms/EQ was considered and rejected as unnecessary complexity for this change; revisit only if a future reviewer requires zero-loss everywhere.

---

Archive Integrity

Moved From: openspec/changes/persistence-corruption-guard/ → openspec/changes/archive/2026-07-11-persistence-corruption-guard/

Copy method: This execution had access only to Read / Write / Edit / Glob / Engram tools — no Bash, shell, or file-deletion tool was available. All 6 artifact files (explore.md, proposal.md, spec.md, design.md, tasks.md, verify-report.md) were reproduced by reading the exact on-disk source content and writing it verbatim to the archive path (no retyping, paraphrasing, or summarizing). Fidelity was spot-checked by re-reading both source and copy at the tail of the two longest files (tasks.md line 154, verify-report.md line 145 — exact match) and at a unicode-heavy table section of design.md (lines 20-29, including ≥, →, — characters — exact match).

NOT a verified true move: because no delete-capable tool was available in this execution context, the original source folder openspec/changes/persistence-corruption-guard/ was left untouched on disk rather than deleted. This is a known, disclosed gap, not a silent failure: content is fully and faithfully duplicated at the archive path and merged into openspec/specs/persistence-resilience/, but the active openspec/changes/ directory will still show persistence-corruption-guard/ until a Bash-capable process (or a human) removes it. Required follow-up: run Remove-Item -Recurse -Force openspec/changes/persistence-corruption-guard (PowerShell) or rm -rf openspec/changes/persistence-corruption-guard (Bash) to complete the move, ideally after an independent diff -r confirms the two folders are identical.

Spec Merged: openspec/specs/persistence-resilience/spec.md created as a new capability domain (no prior main spec existed for this domain — verified via Glob openspec/specs/** returning alarm-pre-notice-countdown, eq-audiofocus, multi-device-eq, bt-device-identity, native-alarms, none named persistence-resilience).

Artifacts Preserved: All 6 openspec files (explore, proposal, spec, design, tasks, verify-report) + new state.yaml + this archive-report.md, all present at the archive path.

---

Sign-Off

Archive Ready For: Production — no blocking issues. Blocking Issues: None. W1 closed, W2 accepted-documented, D4 optional/non-blocking. Outstanding Non-Code Follow-Up: Delete the original openspec/changes/persistence-corruption-guard/ source folder (see Archive Integrity) — a filesystem-hygiene step, not a functional or spec-compliance gap. Recommendation: No further code changes required for this change. Optional S1/S2 fast-follows may be picked up independently at any time.

---

Appendix: Observation IDs for Traceability

• #2350: sdd/persistence-corruption-guard/proposal (intent, scope, shared 3-part fix approach)
• #2351: sdd/persistence-corruption-guard/spec (5 requirement groups, 10 scenarios, persistence-resilience capability)
• #2354: sdd/persistence-corruption-guard/design (6 architecture decisions D1-D6, degraded-flag/write-authority matrix)
• #2359: sdd/persistence-corruption-guard/tasks (61 checkboxes, stacked-to-main work-unit plan, review workload forecast)
• #2360: sdd/persistence-corruption-guard/apply-progress (3 batches merged, 57/57 code tasks + 3/4 Phase D)
• #2363: sdd/persistence-corruption-guard/verify-report (PASS WITH WARNINGS, 10/10 scenarios compliant, W1/W2 findings)
• (this report): sdd/persistence-corruption-guard/archive-report

All artifacts archived and accessible at openspec/changes/archive/2026-07-11-persistence-corruption-guard/ with full change history preserved for audit trail.