feat(stability): unify readiness and recovery

2026-08-01 01:21:33 +02:00
parent 38282e4f7f
commit cd8c78d165
67 changed files with 2616 additions and 601 deletions
@@ -0,0 +1,188 @@
+# Nexus v0.2.60 — Stabilität und Recovery
+
+**Stand:** 2026-07-31
+
+**Status:** Release Candidate; lokale Verträge grün, Linux-/Docker-CI und
+Produktionsdeployment noch auszuführen
+
+**Scope:** Nexus-Repository und kontrollierte Browser-Fixtures. Keine
+produktive OpenClaw-Mutation; Maxis Ressourcen lagen vollständig außerhalb des
+Prüfbereichs.
+
+## Ergebnis
+
+Der erste Stabilitäts- und Fehlerabbau-Slice ist implementiert. Nexus trennt
+jetzt Prozess-Liveness, Datenbank-Readiness und vollständige Runtime-Diagnose,
+liefert einen generierten gemeinsamen Fehlervertrag und zeigt auf allen 20
+authentifizierten Views einheitliche Loading-, Empty-, Error-, Offline-, Stale-
+und Partial-Zustände. Releaseversion, Containerprovenienz, Dependency- und
+Secret-Scans sowie die echten PostgreSQL-/Toxiproxy-Verträge sind Teil der
+CI-Freigabe.
+
+Das ist noch keine vollständige Produktions- oder OpenClaw-Abnahme. Der
+credentialed Owner-Audit, Task-Board-Lastnachweis und jeder produktive
+OpenClaw-Schreibvorgang bleiben getrennte Gates.
+
+## Implementierter Vertrag
+
+### Health, Deployment und Version
+
+- `GET /health/live` ist ein reiner Prozesscheck.
+- `GET /health/ready` prüft ausschließlich Pflichtabhängigkeiten mit dem Tag
+  `ready`; PostgreSQL-Ausfall liefert HTTP 503.
+- `GET /health` bleibt die vollständige Diagnose. Ein OpenClaw-Ausfall ergibt
+  `Degraded`, ohne die Nexus-Recovery-Oberfläche durch Readiness zu sperren.
+- Der API-Container wird über `/health/ready` geprüft. Web wartet auf einen
+  gesunden API-Container; API wartet auf gesundes PostgreSQL.
+- Deployment prüft zuerst die lokale Container-Readiness, danach öffentliche
+  Readiness und den vollständigen Runtimezustand. Rollback verwendet dieselben
+  Gates und akzeptiert HTTP 404 für `/health/ready` nur bei einem sichtbaren
+  Notfall-Rollback auf Versionen vor v0.2.60.
+- `global.json` verlangt .NET `10.0.100` mit `latestFeature`-Roll-forward.
+  `VERSION` ist die Releasequelle; Frontendpaket und OCI-Labels werden dagegen
+  geprüft. Images tragen Version und exakten Git-SHA.
+
+### Auth und Browsergrenze
+
+- Die ungenutzte `/api/v1/auth/csrf`-Route und Antiforgery-Registrierung sind
+  entfernt. Kein Client sendete das Token und keine Mutation validierte es.
+- Das Refresh-Cookie bleibt `Secure`, `HttpOnly` und `SameSite=Strict`.
+- Refresh und Logout weisen explizite Cross-Site-Browseraufrufe anhand von
+  `Origin` und `Sec-Fetch-Site` ab. API-Clients ohne Browser-Provenienzheader
+  benötigen weiterhin das gültige Cookie und unterliegen den normalen Limits.
+- Login-, Refresh- und Rate-Limit-Fehler verwenden denselben strukturierten
+  Problemvertrag.
+- Nach einem fehlgeschlagenen Refresh leitet das Frontend genau einmal zum
+  Login um und erhält das Rückkehrziel.
+- Ein persistierter Refresh-Hash bleibt über eine neu erzeugte Serviceinstanz
+  verwendbar und wird anschließend rotiert. Ein echter Containerneustart wird
+  zusätzlich im produktionsnahen Releaseprofil geprüft.
+
+### Gemeinsame Fehler- und Recovery-Schicht
+
+Backendfehler verwenden `application/problem+json` mit:
+
+- `code`, `status`, `title`, `detail`, `traceId`;
+- optional `operationId`, `currentRevision`, `retryAfterSeconds`, `remaining`;
+- den stabilen Codes `validation_failed`, `unauthenticated`, `forbidden`,
+  `conflict`, `not_found`, `unsupported_capability`,
+  `dependency_unavailable`, `timeout`, `rate_limited` und `internal_error`.
+
+Durable Agent-Proposal-, Run- und andere Operationsendpunkte behalten ihre
+typisierten Envelopes für Zustände wie `partial`, `failed` und `in_doubt`.
+Diese Zustände müssen dauerhaft untersuchbar bleiben und werden nicht als
+flüchtige HTTP-Ausnahme versteckt. Der Frontendadapter normalisiert während der
+Kompatibilitätsphase zusätzlich ältere `message`-/`error`-Payloads.
+
+Ein OpenAPI-Schema-Transformer beschreibt diese Erweiterungen im
+eingecheckten 3.1-Vertrag. Der generierte TypeScript-Client speist `AppProblem`
+und `toAppProblem`; Views raten die Transportstruktur nicht selbst.
+
+`AsyncStatePanel` stellt Loading, Empty, Error, Offline, Stale und Partial
+semantisch dar, zeigt nur technische Trace-/Operation-Metadaten und bietet die
+passende Recovery-Aktion. Sichere GETs dürfen begrenzt wiederholt werden;
+Mutationen werden nie automatisch wiederholt. Sichtbare Daten bleiben bei
+Background-Refresh oder einem Fehler einer sekundären Detailabfrage erhalten.
+
+Migriert wurden:
+
+- Dashboard und Task Strip;
+- Agents, Agent Detail, Agent Create und Proposal Detail;
+- Projects, Project Detail, Task Board und Task Detail;
+- Run Control und Run Detail;
+- Calendar, Memory, Docs und Incidents;
+- Models, Activity, Notifications, Security und Settings.
+
+Memory, Docs und Incidents verlieren ihre bereits sichtbare Liste nicht mehr,
+wenn nur eine Detail- oder Suchabfrage fehlschlägt. Agent Detail blockiert die
+Primäransicht nicht länger wegen einer fehlerhaften Sekundärabfrage.
+
+### CI und Supply Chain
+
+- Ein separater verpflichtender Linux-Job führt alle als
+  `DockerIntegration` oder `ToxiproxyIntegration` markierten Tests mit beiden
+  Opt-ins aus. Fehlendes Docker ist ein Jobfehler, kein Skip.
+- Frontend und Backend blockieren High/Critical-Produktionsabhängigkeiten.
+- Gitleaks `8.30.1` wird als Upstream-Artefakt geladen, über einen gepinnten
+  SHA-256 geprüft und gegen die vollständige Git-Historie ausgeführt.
+- Drei überprüfte historische Fingerprints sind exakt baselined; die aktuelle
+  Arbeitskopie ist redigiert. Eine eventuelle Credential-Rotation oder
+  History-Rewrite bleibt ein gesonderter, ausdrücklich freizugebender
+  Sicherheitsvorgang.
+- Das Fixture-Playwright-Profil deaktiviert Browsertelemetrie. Das
+  Produktionsimage aktiviert nur den allow-listeten bestehenden
+  Browsermetrikpfad über `VITE_BROWSER_TELEMETRY_ENABLED=true`.
+
+## Lokale Abnahme
+
+| Gate | Ergebnis |
+|---|---|
+| Frontend Typecheck | grün |
+| Frontend Unit Tests | 13 Dateien, 42 Tests bestanden |
+| Frontend Production Build | grün |
+| Playwright | 26/26 bestanden |
+| Geschützte Routen | alle 20 in kontrollierten Fixtures geprüft |
+| Viewports | 375, 768, 1024, 1440 und 1920 px ohne Seitenoverflow |
+| Browserverträge | Deep Links, Query-Deduplizierung, ein SSE-Resync, Task-Board-Refresh, Done-Pagination, Drag-and-drop und 503-Recovery grün |
+| Backend | 383 bestanden; fünf Containerfälle mangels lokalem Docker explizit übersprungen |
+| PostgreSQL-Ausfall | echter Npgsql-Healthcheck gegen einen nicht erreichbaren Endpoint liefert im Readiness-Vertrag 503 |
+| Version | `VERSION` und Frontendpaket beide `0.2.60`; .NET-Pin wird als 10.0.101 aus dem erlaubten Feature-Band aufgelöst |
+| Abhängigkeiten | keine bekannten pnpm-Produktionslücken; keine High/Critical-NuGet-Funde |
+| Compose/Workflows | Compose valide, Deploy-Shell syntaktisch valide, CI- und Rollback-YAML parsebar |
+| OpenAPI | neu generiert; entfernte CSRF-Route, neue Readiness-Route und Problemfelder enthalten |
+
+Playwright arbeitet mit kontrollierten API-Fixtures. Diese Ergebnisse beweisen
+die UI- und Transportverträge, nicht die echte Produktionsdatenqualität oder
+OpenClaw-/OpenAI-Ausführung.
+
+## Offene Abnahmegates
+
+### Vor Deployment
+
+1. Der neue Gitea-Linuxjob muss alle fünf vorhandenen PostgreSQL-/Toxiproxy-
+   Containerfälle bestehen, null überspringen und Docker als erreichbar melden.
+2. Der Gitleaks-Vollhistorienjob, OpenAPI-Diff, Dependency-Gates und die übrigen
+   Backend-/Frontendjobs müssen grün sein.
+3. Das versionierte Image muss mit SHA-Provenienz gebaut und durch dieselben
+   Readiness-/Diagnosegates deployt werden.
+
+### Nach Deployment, ohne Owner-Sitzung
+
+- `/health/live`, `/health/ready`, `/health`, `/login`, Security-Header und ein
+  unauthentifizierter geschützter API-Aufruf werden öffentlich geprüft.
+- Die Produktion muss `v0.2.60` und den ausgelieferten Git-SHA melden.
+
+### Mit separater Owner-Sitzung
+
+- Alle 20 authentifizierten Produktionsviews werden read-only auf Navigation,
+  Requests, Konsole, Refresh/Reload/Logout, echte Agent-/Cron-/Modell-/Security-
+  Daten, SSE-Freshness, Tastatur und Overflow geprüft.
+- Kein OpenClaw-Schreibtest wird dabei ausgeführt.
+
+### Noch nicht Teil dieses Release-Slices
+
+- Task Board mit 1.000 Tasks und 10.000 Activities: k6-p95,
+  SQL-Statementzählung, `EXPLAIN (ANALYZE, BUFFERS)` und wiederholte
+  Navigation-bis-Karten-sichtbar-Messung.
+- Produktive Protocol-v4-Verbindung und Management. OpenClaw `2026.7.1`
+  registriert weiterhin keine offiziell unterstützte externe Nexus-/Generic-
+  Operator-ID. Die neuen offiziellen Seiten zu
+  [Gateway clients](https://docs.openclaw.ai/gateway/clients) und
+  [external apps](https://docs.openclaw.ai/gateway/external-apps) ändern den
+  geschlossenen Connect-Schema-/Client-ID-Vertrag noch nicht.
+- Ein echter `Nexus -> OpenClaw -> OpenAI -> Nexus`-Run, Wegwerf-Cron oder
+  Testagent. Diese Mutationen benötigen nach erfülltem Identity-Gate eine
+  separate Owner-Freigabe.
+
+## Nächste Reihenfolge
+
+1. Linux-/Docker-CI und Deployment-Smoke für v0.2.60 abschließen.
+2. Bao meldet sich im In-App-Browser als Owner an; danach 20 Seiten read-only
+   auditieren und jeden Fund mit Route, API, Trace-ID und Regressionstest
+   erfassen.
+3. Task-Board-Datensatz und Last-/SQL-/Browserbudgets isoliert beweisen; nur
+   gemessene Engpässe optimieren.
+4. OpenClaw-Client-ID auf dem ersten kompatiblen Stable-Tag erneut prüfen und
+   erst dann read-only pairen.
+5. Danach Run Explorer, Agent Lifecycle, Notifications/Incidents, Calendar,
+   Knowledge und Security in der bestehenden Roadmap-Reihenfolge schließen.