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
@@ -1,6 +1,6 @@
 # Nexus Agent-First Mission Control

-**Status:** Zielvertrag mit produktiv ausgeliefertem v0.2.59-Control-Plane-Slice; Gateway-Writes, credentialed Live-Abnahme und Lastnachweis offen
+**Status:** Zielvertrag mit produktivem v0.2.59-Control-Plane-Stand und implementiertem v0.2.60-Stabilitätskandidaten; Linux-/Docker-Releasegate, Gateway-Writes, credentialed Live-Abnahme und Lastnachweis offen
 **Stand:** 2026-07-31
 **Geltungsbereich:** Produkt, Frontend, Backend, Runtime-Adapter und Agenten-Schnittstellen

@@ -129,6 +129,31 @@ Produktionscheckpoint v0.2.59 vom 2026-07-31:
 Die vollständige Evidenz und der daraus abgeleitete Plan stehen in
 [Production release v0.2.59](audits/2026-07-31/production-release-v0.2.59/PRODUCTION_VALIDATION_AND_NEXT_PLAN.md).

+Stabilitätscheckpoint v0.2.60 (Release Candidate) vom 2026-07-31:
+
+- `/health/live`, `/health/ready` und `/health` trennen Prozesszustand,
+  PostgreSQL-Readiness und vollständige OpenClaw-Diagnose. Deploy und Rollback
+  verwenden dieselben Gates; ein OpenClaw-Ausfall hält die Recovery-Oberfläche
+  erreichbar.
+- Die ungenutzte Antiforgery-Route ist entfernt. Refresh und Logout behalten
+  das strikte Secure-/HttpOnly-Cookie und weisen explizite Cross-Site-Browser-
+  Aufrufe anhand von `Origin` und `Sec-Fetch-Site` ab.
+- OpenAPI beschreibt den gemeinsamen `ProblemDetails`-Vertrag einschließlich
+  stabilem Code und Trace-ID. Alle 20 authentifizierten Views verwenden die
+  gemeinsame Loading-/Empty-/Error-/Offline-/Stale-/Partial-Schicht und
+  erhalten sichtbare Daten bei Background-Refresh.
+- `global.json`, `VERSION`-Parität, OCI-Provenienz, Browsertelemetrie-Schalter,
+  High/Critical-Abhängigkeitsgates, checksum-verifiziertes Gitleaks und ein
+  verpflichtender PostgreSQL-/Toxiproxy-CI-Job bilden den neuen Releasevertrag.
+- Lokal bestehen 383 nicht-containerisierte Backendtests, 42 Frontendtests,
+  Typecheck, Produktionsbuild und 26 kontrollierte Playwright-Tests. Die fünf
+  Containerfälle sind lokal mangels Docker übersprungen und müssen im Linux-CI
+  mit null Skips bestehen. Credentialed Produktion, Task-Board-Last und echte
+  OpenClaw-Schreibpfade bleiben eigene Gates.
+
+Die genaue Implementierungs- und Evidenzgrenze steht in
+[Stability v0.2.60](audits/2026-07-31/stability-v0.2.60/IMPLEMENTATION_AND_ACCEPTANCE.md).
+
 ## 4. Prioritätsdefinition

 - **P0:** Blockiert sicheren End-to-End-Betrieb oder das Kernversprechen
@@ -450,6 +475,14 @@ regressionsfest.
 - Last-, Reconnect-, Timeout-, Queue-, Recovery- und Chaos-Szenarien prüfen.
 - Runbooks, Backup/Restore und Rollback regelmäßig als Game Day testen.

+**Checkpoint 2026-07-31:** Das v0.2.60-Stabilitätsfundament implementiert
+separate Readiness, einen generierten Fehlervertrag, gemeinsame UI-Recovery,
+ein SDK-/Versionsgate, Supply-Chain-Scans und verpflichtende Containerverträge.
+Der kontrollierte Browserlauf deckt alle 20 authentifizierten Views und fünf
+Breiten ab. Offen bleiben der grüne Linux-/Docker-Run, credentialed
+Produktionsprüfung, der 1.000/10.000-Task-Board-Lastnachweis sowie reale
+OpenClaw-/OpenAI-End-to-End-Evidenz.
+
 **Abnahme:** Ein Release ist nur möglich, wenn technische Checks und ein
 repräsentativer realer Agenten-Workflow gemeinsam grün sind.

@@ -10,6 +10,44 @@ OpenClaw, PostgreSQL, browser, or load-test boundary. Archive the command,
 versions, sanitized output, dataset provenance, and timestamp for every
 acceptance run.

+## Release CI gates
+
+Every push now runs four independent pre-deployment jobs:
+
+- the normal .NET 10 build and test suite plus a High/Critical NuGet
+  vulnerability gate;
+- a mandatory Linux runner job with both
+  `NEXUS_RUN_DOCKER_INTEGRATION_TESTS=true` and
+  `NEXUS_RUN_TOXIPROXY_INTEGRATION_TESTS=true`;
+- frontend version parity, High/Critical production dependency audit,
+  typecheck, generated OpenAPI drift, unit tests, production build and the full
+  Playwright route matrix; and
+- a full-history Gitleaks v8.30.1 scan downloaded from the upstream release and
+  checked against its pinned SHA-256 before execution.
+
+Deployment depends on all four jobs. A missing Docker endpoint is therefore a
+failing integration job, not a successful skip. Local runs without Docker may
+still show five explicit skips, but they are not release acceptance evidence.
+The checked-in `.gitleaksignore` contains only exact fingerprints for reviewed
+historical findings; it is not a pattern-based bypass for new secrets.
+
+The repository SDK contract is `global.json`: .NET `10.0.100` with
+`latestFeature` roll-forward. `VERSION` is the release source of truth;
+frontend package version and OCI image labels are checked against it.
+
+## Browser route and recovery gate
+
+The fixture Playwright profile sets `VITE_BROWSER_TELEMETRY_ENABLED=false`, so
+expected telemetry proxy failures cannot mask application regressions.
+Production container builds enable the allow-listed browser metrics explicitly.
+
+The route suite covers Login plus all 20 authenticated views at 375, 768, 1024,
+1440 and 1920 px. It also checks deep links, shared-query deduplication, one
+targeted resync after an SSE sequence gap, retained Task Board content during a
+refresh, Done pagination, drag-and-drop, and distinguishable dependency
+outage/retry recovery. These are controlled browser contracts, not a
+credentialed production or real OpenClaw acceptance run.
+
 ## Task Board load gate

 The full k6 profile holds ten virtual users for two minutes and fails when:
@@ -1,5 +1,11 @@
 # Nexus – Security Spot Check

+> **Historische Evidenz:** Diese Datei hält den Stand vom 2026-07-26 fest. Der
+> v0.2.60-Stabilitätsslice entfernte die ungenutzte CSRF-Tokenroute, ergänzte
+> Browser-Origin-Prüfungen für Refresh/Logout und ersetzte den einfachen CI-Grep
+> durch checksum-gepinntes Full-History-Gitleaks. Aktuelle Abnahmegrenzen stehen
+> in `docs/audits/2026-07-31/stability-v0.2.60/IMPLEMENTATION_AND_ACCEPTANCE.md`.
+
 **Datum:** 2026-07-26
 **Commit:** `3bc7622977f4a6c2f2e98ab4aa856a2e45c3cf49`
 **Vertraulichkeit:** Intern
@@ -184,7 +184,9 @@ Ebene 4: X-Agent-Id Header (Agent-Identität für Task-State-Enforcement)
 - JWT-Sicherheit entspricht Best Practices (PBKDF2-SHA256, 210k Iterationen, Rotating Refresh Tokens)
 - Refresh-Token-Reuse-Detection verhindert Token-Theft
 - Rate-Limiting auf Login und Refresh
- CSRF-Protection via `X-CSRF-TOKEN` + `nexus-csrf` Cookie
+- Cookie-backed Refresh/Logout über `Secure`, `HttpOnly`, `SameSite=Strict`
+  plus `Origin`-/`Sec-Fetch-Site`-Prüfung; die unvalidierte Legacy-CSRF-Route
+  wurde in v0.2.60 entfernt
 - Security Headers (HSTS, CSP, XFO, Referrer-Policy)

 **Kritisch:**
@@ -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.