Skip to content

feat(storage): Phase 4 – PR 4-B Zeitreihen-Datenbank, Statistik-Neuaufbau und Plan-Snapshots - #26

Open
PXLJAKE wants to merge 12 commits into
claude/zealous-mayer-j5oda9from
phase-4/b-storage
Open

PXLJAKE wants to merge 12 commits into
claude/zealous-mayer-j5oda9from
phase-4/b-storage

Conversation

@PXLJAKE

@PXLJAKE PXLJAKE commented Oct 17, 2026

Copy link
Copy Markdown
Owner

Gestapelt auf #25 (PR 4-A). Basis ist der Branch von 4-A; nach dessen Merge wird die Basis auf main umgestellt.

Was

WP3 aus docs/plans/phase-4.md:

  • /data/timeseries.db mit eigenen Migrationen (suncore/storage/timeseries.py):
    • Messwerte: 48 h roh, 1 min für 30 Tage, 15 min unbegrenzt (mit Kennzeichen „abgeleitet“).
    • Prognosen versioniert nach Ausgabezeit (45 Tage).
    • Preise (400 Tage).
    • Der Nachtjob um 03:30 Ortszeit verdichtet die Daten, löscht Altes und gibt Speicher nur frei (VACUUM), wenn es sich lohnt.
    • Die Datei ist von den HA-Backups ausgenommen (backup_exclude).
    • Eine kaputte Datei wird nur bei eindeutiger Beschädigung beiseitegelegt (mit WAL, höchstens zwei Kopien). Bei gesperrter Datei, voller Platte oder E/A-Fehlern läuft SunCore ohne Zeitreihen weiter und verschiebt nichts.
  • Neuaufbau aus den HA-Statistiken: 28 Tage Anlagenwerte über recorder/statistics_during_period, Periode hour, mit expliziten Einheiten (suncore/ha/statistics.py, suncore/app/history.py). Der Neuaufbau läuft, bis er einmal geklappt hat, mit Back-off. Gemessene Werte werden nie überschrieben.
  • Messwert-Aufzeichnung des Reglers über einen gepufferten Schreiber: alle 60 s, nur Werte mit Qualität OK, Speicher begrenzt.
  • suncore.db Migration 0004: plan_snapshot (komprimiert, 200 Stück / 14 Tage) und learned_param (gelernte Werte für WP5–WP7). DB-Schema 4.
  • Ratenbegrenzer für lesende HA-Aktionen pro domain.service (optional mit Unterschlüssel), Folgepunkt A3 aus Phase 1. Grenzregel 7: nur suncore.app.adapters darf Aktionen aufrufen. Grenzregel 8: statistics_during_period gibt es nur in ha/sim.
  • Behoben: Ein abgebrochener Datenbankzugriff konnte eine Transaktion auf der gemeinsamen Verbindung offen lassen. Das betraf auch suncore.db.

Warum

Prognosegüte, Risikomodell (WP7), Lastprognose (WP6) und Planer (WP8) brauchen Historie, versionierte Prognosen und Preise. Ohne Neuaufbau aus HA würde die Lastprognose wochenlang ohne Daten starten.

Wie getestet

  • ./scripts/check.sh grün: ruff, mypy, 3229 Python-Tests, Abdeckung 96 %, Frontend 219 Tests, Bundle im Budget.
  • Hypothesis-Tests: Beim Verdichten bleibt die Energie erhalten, das Verdichten ist idempotent bei zufälligen Lücken und Jobzeiten, Zeilen liegen auf Eimergrenzen.
  • Regressionstests:
    • Viertelstunde während des Nachtjobs: liest 700 W statt 100 W.
    • Gesperrte Datei: wird nicht verschoben.
    • Abbruch während Flush: der Batch bleibt erhalten.
    • Abbruch einer Transaktion.
    • Sommerzeit beim Nachtjob.
    • Hängender Wartungsjob: die Geräte werden trotzdem sofort freigegeben.
  • Gemessen: Der Primärschlüssel (ts, key) statt (key, ts) senkt die WAL-Schreiblast pro Flush von 131 841 auf 23 897 Bytes (5,5×, schont die SD-Karte).

Risiken

  • DB-Schema 4: Frühere Versionen öffnen die Datenbank nicht mehr. Vor dem Update die Konfiguration exportieren (steht in DOCS.md beider Apps).
  • timeseries.db ist nicht im Backup. Nach einer Wiederherstellung werden nur 28 Tage Viertelstundenwerte neu aufgebaut, keine Prognose-Historie.
  • UNVERIFIED: ob der Supervisor-Proxy recorder/* durchreicht, und change/sum echter Energiezähler. Schlägt der Neuaufbau fehl, läuft SunCore mit Warnung ohne ihn weiter.

Safety-Review

control-safety: freigegeben nach Behebung von M1 (Commit ef3aa20).

  • Messwert-Haken im Regler-Takt: Der on_measurements-Haken im ControlStack-Takt ist synchron, arbeitet nur im Speicher und schluckt Ausnahmen; der ganze Rumpf steht im try. Er kopiert nur OK-Werte in ein neues Dict, die Steuer-Eingaben bleiben unverändert.
  • Grenzregeln: Regel 7 ist verschärft: Nur suncore.app.adapters darf call_action_response aufrufen, und die Allowlist wird vor dem Limiter geprüft. Der Aktions-Limiter ist eine eigene Instanz und berührt die Schreibratenbegrenzung des ServiceCaller nicht.
  • Statistik-Neuaufbau: Er läuft als eigener Task mit Back-off und kann die Regelschleife nicht aushungern.
  • M1 (behoben): Runtime.stop() wartete vor stack.shutdown() auf laufende Speicher-Tasks. Das hätte die Freigabe der Geräte um Sekunden verzögern können. Jetzt laufen Abbruch und stack.shutdown() zuerst, dann wird auf die Speicher-Tasks gewartet. gate.shutdown() liegt weiter vor dem Schließen der Verbindung. Test mit hängendem Wartungsjob.
  • Invarianten aus BRIEF §5: nicht berührt (kein neuer apply()-Pfad, controller/ und safety/ unverändert).

Checkliste

  • Tests für neues Verhalten, Lint/Typen/Tests grün
  • Keine hardcodierten UI-Strings; neue Keys in en und de
  • Doku aktualisiert (DOCS.md: Schema 4 und timeseries.db)
  • docs/STATUS.md aktualisiert
  • Nichts erfunden: Request-Form aus docs/research/ha-websocket-api.md, Offenes als UNVERIFIED

Offene Fragen an den Maintainer

  1. Prognosen speichern: Bei 15-Minuten-Updates fallen etwa 18 000 Zeilen pro Tag und Quelle an. Vorschlag: höchstens stündlich speichern oder wenn sich die Prognose ändert (wird in 4-D so umgesetzt).
  2. Neuaufbau: Nur Anlagenwerte (Netz, PV, Akku, Haus). Für einzelne Geräte gibt es in HA keine Statistik. Für den Start der Lastprognose reicht das. Einverstanden?
  3. Ratenbegrenzung: Eine Überschreitung meldet sich als Fehler (ActionRateLimitedError) und nicht als stilles Ergebnis, damit Adapter sie nicht übersehen. Passt das?
  4. Datenbankgröße: Sie steht noch auf keiner Diagnoseseite, und eine zu neue timeseries.db erscheint nur im Log. Der Hinweis in der Oberfläche kommt mit 4-H.

Generated by Claude Code

claude added 12 commits October 17, 2026 02:44
…lan snapshots (WP3)

- timeseries.db as a separate SQLite file with its own migrations: raw measurements (48 h),
  1-minute (30 days) and 15-minute aggregates (unlimited), forecasts versioned by issue time,
  prices; TimeseriesStore with batched appends, core-series round trips, latest forecast
  before t, idempotent nightly downsample/retention and VACUUM only when worth it.
- Rebuild of the 15-minute history from recorder/statistics_during_period (hour period,
  explicit units, chunked), stored as derived rows; HAConnection.statistics_during_period
  plus a recorder fake in the simulator.
- suncore.db migration 0004: plan_snapshot and learned_param with small repositories
  (schema 4; earlier versions refuse it).
- Per-(domain, service) rate limiter with try-acquire/deadline for call_action_response
  (follow-up A3); boundary rule 7 admits suncore.app.adapters only.
- Runtime wiring: batched measurement recorder (flush every 60 s), nightly job, rebuild after
  the first connect; errors are logged and never reach the control loop.
- Fix: a cancelled writer could leave a transaction open on the shared connection.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VHXsfH6PkT62o9idByAd6e
Only SQLite's "not a database"/"malformed" errors and a failing PRAGMA quick_check move the
file; a locked, busy, full, unreadable or permission-denied database is logged and the app
runs without time series (retry on the next start, nothing moved). The file is moved with its
-wal/-shm as timeseries.db.corrupt-<UTC>, the newest two are kept, and timeseries.db.corrupt*
is excluded from backups in both apps. The open now happens inside the try of build_runtime.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VHXsfH6PkT62o9idByAd6e
…red beats derived

- measurement and measurement_1m use PRIMARY KEY (ts, key) (schema unreleased, 0001 changed).
  One flush now touches the last pages of the table instead of one page per key. Measured on a
  48 h preload with 10 keys, 120 rows per flush, WAL bytes per flush: (key, ts) 131841,
  (ts, key) 23897 (5.5x less). Per-key range reads seek on ts (query-plan test); no extra index.
- downsample writes the 1-minute tier only up to floor(now, 15 min), so a bucket is either whole
  in measurement_1m or whole in the raw rows and read_series never mixes the two inside one
  quarter hour (regression test with the review example: job at 03:35, 5 min x 100 W then
  10 min x 1000 W reads 700 W).
- read_series: a derived (rebuilt) row never beats data measured live.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VHXsfH6PkT62o9idByAd6e
The rebuild no longer depends on "measurement_15m is empty" (which a maintenance run or the
first samples defeated). A marker row in timeseries.db (table meta, key history_rebuilt_at;
it dies with the file) is set after a successful rebuild. A timeout or Home Assistant error is
retried after 1, 5, 15 and then every 60 minutes; unknown_command is final for the process.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VHXsfH6PkT62o9idByAd6e
…lation paths

- MeasurementRecorder.flush puts the batch back on any BaseException (shutdown cancels the flush
  loop) and re-raises; the 7 hours (not 100 minutes) of the buffer cap are documented correctly.
- Database: Transaction.executemany closes its cursor even if the task is cancelled, and the
  retrieved outcome of the shielded rollback no longer raises "exception never retrieved".
- Includes the earlier fix that a cancelled writer could leave a transaction open on the shared
  connection ("cannot start a transaction within a transaction"; rollback is now queued behind
  the cancelled statements and shielded). It affects suncore.db as well.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VHXsfH6PkT62o9idByAd6e
…al connection

call_action_response takes rate_key (e.g. the target entity or date): the limiter key is
domain.service or domain.service#key, so two different calls of one service do not block each
other. A cancelled waiter keeps its reservation (documented, tested). FakeHAConnection uses the
same ActionRateLimiter, so adapter tests meet the real behaviour.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VHXsfH6PkT62o9idByAd6e
…s twice

The loop wakes at most hourly and targets "the first 03:30 after the last run" in the current
zone, so a zone that becomes known after start (Home Assistant's) moves the target instead of
leaving a stale 24 h sleep, and a wake-up cannot repeat a run.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VHXsfH6PkT62o9idByAd6e
Energy (sum of mean x n and min/max) is preserved per complete quarter hour and in the
1-minute tier, downsampling is idempotent for random gaps and job times, and rows sit on
bucket boundaries strictly before floor(now, 15 min).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VHXsfH6PkT62o9idByAd6e
4-B moves to Done, header updated, two UNVERIFIED rows added (recorder/* via the proxy,
change/sum of real counters and the backup_exclude glob), follow-ups noted (size_report not on
a diagnostics page, a too-new timeseries.db is only logged).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VHXsfH6PkT62o9idByAd6e
…ick hook and the action call

- Runtime.stop cancels the storage tasks (prune, flush, maintenance, history) but awaits them
  only after ControlStack.shutdown(): a running downsample or retention statement keeps the
  shielded rollback of its cancelled task waiting, which must not delay the device release
  (the gate still shuts down before the connection closes). Test with a stuck maintenance task.
- ControlStack._record_measurements builds the values inside the try as well.
- call_action_response checks the connection before taking a rate-limit slot.
- Boundary rule 8: statistics_during_period only in suncore.ha and suncore.sim.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VHXsfH6PkT62o9idByAd6e
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.

2 participants