Capture and safely recover shared LLM responses with bounded field repairs

docs/shared-answer-recovery.md

@@ -0,0 +1,114 @@
+# Gemeinsame Antwortverwertung und Fehlererfassung
+
+## Geltungsbereich
+
+Beide HTTP-Adapter (Gemini nativ und OpenAI-kompatibel) erfassen Modellantworten
+phasenunabhängig. Gemeinsame lokale Formatbehandlung gilt auch für Namensauflösung,
+Interpretation, Hypothesengenerierung, Untersuchung, Diagnose und Übergabe.
+Die bestehenden phasenspezifischen Prüfer bleiben verbindlich. Fachliche Artefakte
+werden weiterhin erst nach vollständiger Annahme veröffentlicht; aus einer
+teilweise ungültigen Antwort wird kein Rechercheauftrag ausgeführt.
+
+## Erfassung
+
+`outcome.response_capture` enthält SHA-256 des UTF-8-Kandidatentextes, Bytezahl,
+Vollständigkeit und entweder den vollständigen Text oder `retained=false`.
+Keine abgeschnittenen JSON-Fragmente als vermeintlich vollständige Kopie.
+Bei Tool-/Refusal-Ausgaben werden die nicht zum Denken gehörenden Kandidatenteile
+als nicht vollständige Antwort archiviert. HTTP-Header, Schlüssel und interne
+Denktexte werden nicht übernommen. Betriebslogs enthalten nur sichere Codes und
+Metadaten; Kandidatentext liegt ausschließlich in der Fallakte.
+
+Konfiguration unter `[llm]`:
+
+```toml
+response_capture_bytes = 65536
+max_field_repairs = 1
+```
+
+Capture ist zusätzlich durch `max_response_bytes` und die 64-KiB-Sicherheitsgrenze
+der aktuellen Recovery-Version begrenzt. Größere Antworten behalten Hash und Größe.
+Dies ist keine Grenze des Case-Paketformats. `max_field_repairs` ist in Version 1
+0 oder 1. Null deaktiviert Modell-Ersatzaufträge; die Erfassung bleibt aktiv.
+Die neuen Standardwerte werden aus dem Konfigurationssnapshot ausgelassen, damit
+unveränderte alte Operationen ihren Konfigurationshash behalten.
+
+Schemafehler behalten zusätzlich das begrenzte strukturierte `rejected_document`.
+Bei fachlicher Ablehnung befindet sich das Dokument bereits in der erfolgreichen
+Protokollantwort; der Phasenfehler verweist auf diesen Call.
+`response_assessment` bezeichnet die Protokoll-/Reparatureinordnung, nicht die
+fachliche Annahme: protocol_valid, normalized_protocol_valid,
+rejected_incomplete, rejected_syntax, schema_field_candidate,
+rejected_other_schema oder no_candidate. Historisch fehlende Originalantworten
+lassen sich nicht nachträglich wiederherstellen.
+
+## Lokale Korrekturen ohne Modellaufruf
+
+- Ein einzelner äußerer JSON-Codeblock und eine einmal JSON-kodierte Rootstruktur.
+- Höchstens zwei Trennzeichenkorrekturen an vom JSON-Parser gemeldeten Positionen:
+  fehlendes Komma / fehlender Doppelpunkt bzw. ein nachgestelltes Komma.
+- Schema-eindeutige Objektstrings und ein einzelnes vollständiges Objekt an
+  einer Arrayposition. Diese Normalisierung wird nur übernommen, wenn anschließend
+  das gesamte Antwortschema gültig ist.
+
+Keine Änderungen innerhalb von Strings, Zahlenkonvertierungen, erfundenen
+Schlüsseln/Werten, Ergänzung fehlender Endklammern oder Akzeptanz doppelter Keys.
+Unvollständige Anbieterantworten (z.B. MAX_TOKENS/length) bleiben abgelehnt, auch
+wenn ihr Text durch kosmetisches Schließen scheinbar parsebar würde.
+Normalisierungen speichern Regeln und Ausgangsdarstellung. Vollständige
+Schema-/Provenienz-/Aktions-/Budgetprüfungen folgen weiterhin.
+
+## Gezielte Modellkorrektur
+
+Die Infrastruktur unterstützt exakt einen Ersatzpfad und unveränderten Rest.
+Der erste ausdrückliche Vertrag umfasst unabhängige redaktionelle Titel:
+Root-Titel, Hypothesentitel und Human-Dev-Titel. Ein einzelner entsprechender
+Schemafehler bzw. ein doppelter Hypothesentitel bei unterschiedlichen Mechanismen
+kann gezielt ersetzt werden. Fehlende oder unbekannte Belege, IDs, Confidence,
+Status, Toolaktionen und kausale Aussagen sind keine solchen Titelkorrekturen.
+Weitere fachliche Ersatzfelder benötigen eigene Abhängigkeitsregeln.
+
+Vor einem Aufruf wird mit einem temporären Titel geprüft, ob andere Schema- oder
+fachliche Fehler bestehen. Der temporäre Wert wird niemals übernommen oder als
+Beleg gespeichert. Bei weiteren Fehlern wird kein nutzloser Ersatzaufruf gestartet.
+Ein unveränderlicher `recovery-declined-NNNN.json`-Nachweis hält den zusätzlichen
+Phasenfehler und den Hash der betroffenen Antwort fest.
+
+`response_field_repair_v1` erhält das betroffene Objekt, gegebenenfalls die übrigen Titel,
+den Zielpfad, den Hash der vollständigen Ausgangsantwort und den Feldvertrag. Es erhält nicht erneut den vollständigen ursprünglichen
+Case-/Toolkontext. Die Antwort ist nur `{replacement: ...}`. Zusätzliche Felder,
+neue numerische/ID-Behauptungen, Änderungen außerhalb des Pfads und weiter
+ungültige Gesamtdokumente werden abgelehnt. Die unabhängigen fachlichen Prüfer
+prüfen danach nochmals die gesamte zusammengesetzte Antwort.
+
+## Persistenz, Abbruch und Metriken
+
+Original und Ersatz sind getrennte normale `llm/operations`-Aufrufe mit eigenen
+Request-/Response-Artefakten und tatsächlichen Usage-Werten. Es gibt keine
+Reparaturmodellschleife im HTTP-Adapter/Gateway. Der CaseRunner darf pro Antwort
+höchstens einen zusätzlichen, separat gespeicherten Ersatzauftrag ausführen.
+Transport-Retry/Failover bleibt davon getrennt und wiederaufnehmbar. Ein gespeicherter
+Ersatz wird nach einem Absturz wiederverwendet; Konfigurationsfehler werden nicht
+als bloße Modellfehler versteckt.
+
+Der Zusammensetzungsnachweis ist ein weiterer Round-Datensatz der Originaloperation
+mit `derived=true` und `outcome.response_recovery`: Referenzen und Hashes von
+Original/Ersatz. Er ist keine weitere Modellantwort und enthält Usage/Kosten/Zeit
+mit dem Wert 0. Kosten-/Call-Auswertungen müssen `derived=true` aus den echten
+API-Aufrufzahlen ausschließen; die tatsächlichen Kosten stehen ausschließlich an
+den beiden echten Calls. Das verhindert Doppelzählung.
+
+Beim Lesen/Wiederaufnehmen werden Quellen, Request-/Response-Hashes, Identität,
+Schema, Zielpfad und exakte Zusammensetzung erneut geprüft. Zyklen abgeleiteter
+Nachweise sind unzulässig. Die bisherigen Ermittlungs-Formatkorrekturen bleiben
+zusätzlich verfügbar und weiterhin auf ihre eigenen expliziten Pfade begrenzt.
+
+## Lokale Prüfungen
+
+Tests decken Parsergrenzen, unveränderte literale Werte, Ablehnungs-Capture,
+Abschneidung, geheime Antworttexte außerhalb von Logs, Teilkorrekturen,
+fachliche Vorprüfung, Registry-Wiederverwendung, manipulierte Zusammensetzung,
+Abbruch nach gespeichertem Ersatz und Transport-Retry ohne Neugenerierung ab.
+Kein zusätzlicher kostenpflichtiger API-Test wurde ausgeführt. Ein späterer
+Realtest muss die Summe aus Erst-, Ersatz- und gegebenenfalls vollständigen
+Korrekturaufrufen bewerten; kleinere Ersatzprompts allein beweisen keine Ersparnis.