# Ambiguous Product-Acquisition sicher aufloesen Dieses Runbook gilt fuer eine `TenantProductAcquisition`, deren Mollie-`POST /payments` moeglicherweise erfolgreich war, deren Antwort HiveGrid aber nicht erhalten hat. Der Ledger bleibt dann absichtlich als `provider_pending` ohne `providerPaymentId` stehen. Dieser Zustand darf weder per manuellem Datenbank-Update noch durch einen neuen Checkout freigegeben werden: Ein noch existierendes Mollie-Payment koennte sonst parallel zum neuen Versuch bezahlt werden. Der einzige freigegebene Operatorpfad ist: ```bash pnpm exec tsx packages/cli/bin/hivegrid-cli.mjs ops product-acquisition-recovery \ --tenant \ --acquisition-id \ --json ``` Das Kommando ist standardmaessig read-only. Es setzt den Tenant im RLS-Kontext, verlangt einen aktiven Plattform-`AdminUser` aus `HIVEGRID_CLI_OPERATOR_USER_ID` und benoetigt die vorhandenen `DATABASE_URL`-, `MOLLIE_API_KEY`-, `LAGO_API_URL`- und `LAGO_API_KEY`-Werte des Ziel-Environments. Provider-Secrets oder Provider-Payloads duerfen nicht in Shell-History, Tickets oder Logs kopiert werden. ## Sicherheitsvertrag Das Kommando gibt einen neuen Versuch nur frei, wenn alle Bedingungen gleichzeitig erfuellt sind: 1. Tenant und Acquisition stimmen exakt mit dem RLS-gebundenen Datensatz ueberein. 2. Der Zustand ist ein explizit mehrdeutiger `provider_pending`-Versuch ohne `providerPaymentId` oder ein bereits begonnenes, weiterhin blockiertes `cleanup.operator_provider_non_creation_confirmed`. 3. Das unveraenderliche Mollie-Maximalfenster plus Reconciliation-Grace ist abgelaufen. Vorher bleibt der automatische Reconciler alleiniger Owner. 4. Die Mollie-Customer-ID und das exakte Attempt-Reference sind vorhanden. 5. Eine live ausgefuehrte, vollstaendig paginierte Mollie-Suche hat auf keiner Seite ein Payment mit diesem Attempt-Reference gefunden. Der Apply-Lauf wiederholt diese Suche nach dem dauerhaften Retry-Block ein zweites Mal und schliesst damit auch die Provider-/DB-Race. Fremde, zyklische, ungueltige oder unbegrenzt fortgesetzte Pagination-Links brechen fail-closed ab. 6. Der Operator bestaetigt bei `--apply` exakt das vom Plan-Lauf ausgegebene Attempt-Reference und gibt eine Audit-Begruendung an. 7. Der Ledger wird zuerst in einen `cleanup.*`-Zustand versetzt. Damit sind Reconciler und User-Retry blockiert, bevor ein externer Cleanup beginnt. 8. Erst nach erfolgreichem Cleanup der exakt gespeicherten Lago-Subscription beziehungsweise Lago-Invoice wird `operator.provider_non_creation_confirmed` gespeichert. Erst dieser Zustand darf durch den normalen Checkout in einen neuen, hochgezaehlten Provider-Attempt ueberfuehrt werden. Ein `provider_payment_found` ist ausdruecklich **kein** Retry-Proof. In diesem Fall nichts freigeben: solange der Ledger noch `provider_pending` ist, den `worker-general`-Reconciler beobachten. Steht er bereits in `cleanup.*`, bleibt er sicher blockiert und der gefundene Providerzustand muss als Billing-Incident untersucht werden. ## Anwenden 1. Den read-only Lauf ausfuehren und nur bei `status=absence_verified` fortfahren. Das ausgegebene `attemptReference` und `observedAt` sind der redigierte Proof; keine Mollie-Antwort anhaengen. 2. Das gleiche Kommando erneut ausfuehren. Der Apply-Lauf wiederholt die exhaustive Live-Suche, er vertraut nicht auf das Ergebnis des ersten Prozesses: ```bash pnpm exec tsx packages/cli/bin/hivegrid-cli.mjs ops product-acquisition-recovery \ --tenant \ --acquisition-id \ --apply \ --confirm-attempt '' \ --reason 'Mollie-Suche und Incident-Pruefung bestaetigen: kein Payment angelegt.' \ --json ``` 3. Nur `status=released_for_retry` erlaubt einen neuen User-Checkout. Der naechste Checkout verwendet einen hoeheren `providerAttempt`, ein neues externes Attempt-Reference und einen dazu gebundenen Idempotency-Key. 4. Im Audit muessen die beiden Aktionen `billing.product_acquisition.operator_recovery_started` und `billing.product_acquisition.operator_recovery_released` fuer dieselbe Acquisition vorhanden sein. ## Fehler und Wiederaufnahme | Ergebnis | Bedeutung | Aktion | |---|---|---| | `absence_verified` | Read-only Mollie-Negativproof erfolgreich | Mit exaktem Attempt und Begruendung erneut als `--apply` ausfuehren | | `provider_payment_found` | Payment existiert oder ist inzwischen sichtbar | Kein Retry; Reconciler beziehungsweise Billing-Incident verfolgen | | `refused` | Status, Zeitfenster, Customer-ID oder Provider-Target erfuellt den Vertrag nicht | Ursache korrigieren, nichts manuell freigeben | | `raced` | Ledger hat sich waehrend der CAS-Operation geaendert | Von vorne read-only inspizieren | | Prozessfehler nach `operator_recovery_started` | Lago-Cleanup oder Abschluss-Persistenz fehlgeschlagen | Dasselbe Kommando erneut ausfuehren; `cleanup.*` bleibt retry-blocking und der Cleanup ist idempotent | | `released_for_retry` | Mollie-Nichtanlage und Lago-Cleanup sind belegt | Neuer Checkout darf normal durch den User gestartet werden | Direktes BullMQ-Retry, `hivegrid-cli outbox requeue`, ein Status-Update per SQL oder das Loeschen des Acquisition-Datensatzes ersetzen diesen Ablauf nicht. Sie koennen weder die Mollie-Nichtanlage noch den exakten Lago-Cleanup beweisen. ## Nachweis ohne Geheimnisse Fuer Ticket oder Incident reichen: Environment, Acquisition-ID, Status, Attempt-Reference, `observedAt`, Audit-Aktionsnamen und der spaetere Reconciler-/Checkout-Status. Nicht aufnehmen: Provider-API-Antworten, Provider-Customer-/Payment-IDs, Credentials, Datenbank-URLs, Cookies oder personenbezogene Checkoutdaten.