trading-system-docs/tolaria/c5-sync-service/C5_DELETE_EXECUTION_ARCHITECTURE_DECISION.md

# C5 DELETE EXECUTION CONTRACT — ARCHITECTURE DECISION RECORD

**Status:** ACCEPTED (Christian, OPTION 1 — CONTRACT-ERWEITERUNG, 2026-08-26)
**Scope:** C5 Sync Service — kontrollierter Tolaria-DELETE-Pfad NACH expliziter Human-Freigabe
**Datei:** `tolaria/c5-sync-service/C5_DELETE_EXECUTION_ARCHITECTURE_DECISION.md`

---

## 1. Ausgangslage / DELETE_EXECUTION_CONTRACT_GAP

STRICT PRE-FLIGHT (read-only) hat den bestehenden DELETE-Contract vollständig analysiert
(`rq_c5a.py`, `rq_c5b.py`, `rq_c5c.py`, `rq_c5d.py`, `rq_c5e.py`, `rq_c5_cli.py`,
`C5AStore`, `TolariaClient`, Tests C5A–C5E). Ergebnis:

| Owner | Verantwortlich | Status |
|---|---|---|
| DELETE_DETECTION_OWNER | C5B `ChangeClassifier.classify()` (Z.520–523): `path_before && !path_after` → `OP_DELETE_REQUEST` | vorhanden |
| DELETE_HUMAN_GATE_OWNER | C5A `SyncStateMachine.process_commit()` (Z.794–797) + C5C `_propagate_object()` (Z.492–496) → `ST_HUMAN_REVIEW_REQUIRED` + `RC_AMBIGUOUS_DELETE` | vorhanden (terminal) |
| DELETE_APPROVAL_STORAGE | **fehlt** — C5AStore hat keine Approval-Repräsentation (nur `meta`, `commits`, `objects`, `bootstrap`, `health`) | GAP |
| DELETE_EXECUTION_OWNER | **fehlt** — `TolariaClient` hat keine `delete()`; kein Executor | GAP |
| DELETE_VERIFICATION_OWNER | **fehlt für DELETE** — `verify()` nur für Writes (Read-Back+Hash); kein DELETE-absent-Read-Back | GAP |
| DELETE_REPLAY_OWNER | C5E `recover()`/`replay()`: `ST_HUMAN_REVIEW_REQUIRED` → `REC_HUMAN_REVIEW` (kein Executor) | GAP |
| DELETE_APPLIED_OWNER | C5D `apply_commit()` → `ST_APPLIED`+`mark_applied()`, startet nur aus `ST_UPDATING_SEARCH` — DELETE-Commit erreicht das nie | GAP |

**Kernbefund:** DELETE wird erkannt und zum Human Gate geführt, aber das Gate ist **terminal**.
Es existiert kein Approval-Storage, kein Executor, kein DELETE-Read-Back, kein Replay- und
kein APPLIED-Pfad. Dies ist der `DELETE_EXECUTION_CONTRACT_GAP`, der durch diese Mission
sauber geschlossen wird.

---

## 2. ZIELARCHITEKTUR (verbindlich)

```
DELETE erkannt (C5B)
  → HUMAN_REVIEW_REQUIRED (C5A/C5C, RC_AMBIGUOUS_DELETE)   [bleibt erhalten]
  → explizite Human Approval (CLI approve-delete)          [NEU]
  → Approval persistent/auditierbar (C5AStore)              [NEU]
  → kontrollierter Tolaria DELETE (DeleteExecutor)          [NEU]
  → Read-Back-Verifikation (target absent)                  [NEU]
  → C5D Source Build (bestehender Pfad)                     [wiederverwendet]
  → Search Update (bestehender C5D-Pfad)                    [wiederverwendet]
  → Exact-Set-Verifikation (C5D verify_integrity)           [wiederverwendet]
  → APPLIED (C5D mark_applied)                               [wiederverwendet]
```

**KEIN automatischer DELETE.** Der bestehende Sicherheitsmechanismus
`OP_DELETE_REQUEST → HUMAN_REVIEW_REQUIRED → RC_AMBIGUOUS_DELETE` bleibt unverändert.

---

## 3. Zwingende Invarianten (A–N) und ihre Umsetzung

| Invariante | Umsetzung |
|---|---|
| **A) DELETE bleibt HUMAN_GATED** | Kein Pfad führt einen DELETE ohne persistierte, explizite Human-Approval aus. `_HUMAN_GATE_OPS` unverändert. |
| **B) Kein LLM/Agent entscheidet, dass DELETE genehmigt ist** | Approval wird AUSSCHLIESSLICH durch den CLI-Befehl `approve-delete` erzeugt (Human Gate). Kein Code erzeugt Approval automatisch. |
| **C) Approval stammt explizit vom Human Gate** | `approve-delete` persistiert `approved_by` (Human-Gate-Provenance) + `approval_nonce`. |
| **D) Approval commit- und objectchange-spezifisch** | Approval bindet exakt `(workflow_commit, object_change_id, object_id, path)`. Keine globale `DELETE_APPROVED=true`-Semantik. |
| **E) Approval für Objekt A nie Objekt B** | Executor validiert `object_id` + `path` gegen die Approval. Abweichung → FAIL CLOSED. |
| **F) Approval für Commit X nie DELETE aus Commit Y** | Approval bindet `workflow_commit`. Executor validiert Commit-SHA. |
| **G) Approval persistent und crash-/restart-fest** | SQLite-Tabelle `delete_approvals` in C5AStore (atomic, WAL, restart-safe). |
| **H) Execution idempotent** | Pre-Delete-Drift-Check + Read-Back. Wenn Ziel bereits absent → `DELETE_ALREADY_AT_TARGET`, kein zweiter destruktiver Write. |
| **I) DELETE nur exakt freigegebenes Objekt** | Executor nimmt `path`/`object_id` ausschließlich aus dem ObjectChange, das durch die Approval gebunden ist. |
| **J) Kein Pfad nimmt beliebige freie Paths/IDs ohne ObjectChange+Approval** | Executor verlangt existierendes ObjectChange (`operation==DELETE`) + exakt passende Approval. Kein freier Pfad-Parameter. |
| **K) Tolaria DELETE vor und nach Execution verifiziert** | Pre-Delete-Drift-Check (Objekt existiert noch) + Post-Read-Back (target absent + kein anderes Objekt verändert). |
| **L) Keine manuelle SQLite-/SQL-State-Manipulation** | Nur Store-Methoden. Kein direktes SQL im Executor. |
| **M) Keine direkte APPLIED-Markierung** | APPLIED nur durch C5D `apply_commit()` nach vollem Search-PASS. Executor markiert NIE APPLIED. |
| **N) Keine automatische Human-Gate-Deaktivierung** | `_HUMAN_GATE_OPS` unverändert; DELETE bleibt Gate-pflichtig. |

---

## 4. APPROVAL CONTRACT

**Prüfung bestehender State:** C5AStore besitzt KEINE geeignete persistente
Approval-Repräsentation (nur `meta`-KV für source_provenance, `commits`, `objects`,
`bootstrap`, `health`). → **Neuer minimaler auditierbarer Approval-State.**

### 4.1 Schema (neue Tabelle `delete_approvals` in C5AStore)

```sql
CREATE TABLE IF NOT EXISTS delete_approvals (
    approval_id      TEXT PRIMARY KEY,          -- UUID, eindeutig
    workflow_commit  TEXT NOT NULL,            -- Commit-SHA (Invariante F)
    object_change_id INTEGER NOT NULL,         -- FK auf objects.id (Invariante D/E)
    object_id        TEXT NOT NULL,            -- exakt freigegebenes Objekt (E/I)
    path             TEXT NOT NULL,            -- exakter Vault-Pfad (E/I)
    operation        TEXT NOT NULL DEFAULT 'DELETE',
    approval_status  TEXT NOT NULL,            -- APPROVED | USED | REVOKED
    approved_by      TEXT NOT NULL,            -- Human-Gate-Provenance (C)
    approval_nonce   TEXT NOT NULL,            -- eindeutig, verhindert Reuse
    approved_at      INTEGER NOT NULL,
    used_at          INTEGER,
    UNIQUE(workflow_commit, object_change_id, object_id, path)
)
```

**Keine Credentials, keine personenbezogenen Daten.** `approved_by` = Human-Gate-Identifier
(z.B. `human:christian`), kein Secret.

### 4.2 Keying

Approval ist eindeutig gebunden an `(workflow_commit, object_change_id, object_id, path)`.
Keine globale `DELETE_APPROVED=true`-Semantik. Ein Approval autorisiert GENAU EINEN
ObjectChange in GENAU EINEM Commit.

### 4.3 CLI-Modell (kein undifferenzierter approve+delete-Blackbox)

Bevorzugtes Modell (Mission §3):
1. `c5-delete approve --commit <sha> --object-id <id> --path <path>` → persistiert Approval (NUR Approval, KEIN DELETE)
2. `c5-delete execute --commit <sha>` → führt DELETE aus (verlangt persistierte Approval)
3. `c5-delete status --commit <sha>` → read-only Status
4. `c5-delete replay --commit <sha>` → idempotenter Replay nach Crash

Der Human-Gate-Beweis (persistierte Approval) geht dadurch NIE verloren.

---

## 5. TOLARIA DELETE CLIENT

`TolariaClient.delete(vault_path)` — minimal, isoliert:

```python
def delete(self, vault_path: str) -> Dict[str, Any]:
    """Loescht ein Vault-Objekt (POST /delete). NUR DeleteExecutor darf rufen."""
    resp = self._post("delete", {"path": vault_path})
    if resp is None:
        resp = {}
    if "error" in resp:
        raise TolariaWriteError(f"Tolaria delete fehlgeschlagen: {resp['error']}",
                                RC_INVALID_SCHEMA)
    return resp
```

**Endpoint-/Payload-Contract** wird ausschließlich aus dem vorhandenen Tolaria-Code/Router
und der dokumentierten Incident-Evidence bestimmt (POST `/api/vault/delete` mit
`{"path": ...}`). **KEINE produktive Endpoint-Probe.** Die Incident-Regel gilt verbindlich:
`NO MUTATING HTTP METHOD PROBES DURING PRODUCTION READ-ONLY DISCOVERY`.

---

## 6. DELETE EXECUTION (DeleteExecutor)

### 6.1 Pre-Delete-Gates (alle MÜSSEN passen, sonst FAIL CLOSED)

1. ObjectChange existiert (`get_object_change`)
2. `operation == DELETE`
3. Commit-Status == `ST_DELETE_APPROVED` (definierter approved state)
4. Approval existiert, `approval_status == APPROVED`, gehört exakt zu diesem ObjectChange
5. `object_id` stimmt (Approval ↔ ObjectChange)
6. `path` stimmt (Approval ↔ ObjectChange)
7. Pre-Delete-Drift-Check: Tolaria enthält das Objekt noch (erwarteter aktueller Zustand)

Bei irgendeiner Abweichung → **FAIL CLOSED** (kein DELETE, kein State-Übergang).

### 6.2 Execution

- `client.delete(vault_path)` (nur DeleteExecutor)
- **Read-Back:** `client.read(vault_path) is None` → target absent == TRUE
- **Zusätzlich:** `client.list()` — kein anderes Objekt verändert (Set-Vergleich vor/nach)

### 6.3 Nach erfolgreichem DELETE

- Approval → `USED` (einmalig, verhindert Reuse)
- Commit → `ST_UPDATING_SEARCH` (C5D übernimmt Search-Pfad)

---

## 7. IDEMPOTENZ / CRASH-RECOVERY (Fälle A–F)

| Fall | Zustand | Deterministischer Replay-Pfad |
|---|---|---|
| **A) Crash vor Approval** | `ST_HUMAN_REVIEW_REQUIRED`, keine Approval | Nichts zu tun. Kein DELETE. Replay: bleibt Human Gate. |
| **B) Crash nach Approval, vor DELETE** | `ST_DELETE_APPROVED`, Approval persistiert | Replay: Executor erkennt Approval, führt DELETE aus. |
| **C) Crash während DELETE** | `ST_DELETING` | Replay: Read-Back. Objekt noch da → DELETE erneut (Approval gültig). Objekt absent → `DELETE_ALREADY_AT_TARGET`, weiter zu `ST_UPDATING_SEARCH`. |
| **D) Crash nach DELETE, vor Read-Back** | `ST_DELETING` | Replay: Read-Back → absent → weiter zu `ST_UPDATING_SEARCH`. |
| **E) Crash nach Read-Back, vor Search Update** | `ST_UPDATING_SEARCH` | C5D `apply_commit()` übernimmt (bestehender Pfad). |
| **F) Crash nach Search Update, vor APPLIED** | `ST_VERIFYING_SEARCH` | C5D `apply_commit()` übernimmt (bestehender Pfad). |

**DELETE_ALREADY_AT_TARGET:** Wenn Tolaria das freigegebene Objekt bereits nicht mehr
enthält, erkennt der Executor anhand Approval + erwarteter Identität + Read-Back
`DELETE_ALREADY_AT_TARGET` statt blind erneut zu mutieren.

---

## 8. SEARCH CONTRACT

Nach erfolgreichem Tolaria-DELETE wird Search NICHT über einen statischen/improvisierten
Pfad aktualisiert. Der bestehende C5D-Pfad wird wiederverwendet:

```
Tolaria current verified state (ohne gelöschtes Objekt)
  → SearchSourceBuilder.build() (read-only, deterministisch)
  → atomic source + Provenance-Persistenz (persist_search_source_provenance)
  → Search-Rebuild (search.rebuild)
  → Exact-Set-Verifikation (verify_integrity: expected IDs/Paths exakt)
  → APPLIED (mark_applied)
```

**Kein APPLIED bei Search-Mismatch** (C5D `_handle_failure` → Human Gate / DEAD).

---

## 9. STATE MACHINE CHANGES

Neue Zustände (minimal, nur für den DELETE-Execution-Pfad):

- `ST_DELETE_APPROVED = "DELETE_APPROVED"` — nach Approval, vor Execution
- `ST_DELETING = "DELETING"` — während Execution (Crash-Window)

Neue erlaubte Transitionen (NUR durch DeleteExecutor/Approval auslösbar, nie automatisch):

```
(ST_HUMAN_REVIEW_REQUIRED, ST_DELETE_APPROVED)   # nur via expliziter Approval
(ST_DELETE_APPROVED,       ST_DELETING)          # Executor startet
(ST_DELETING,              ST_UPDATING_SEARCH)   # nach DELETE + Read-Back → C5D
(ST_DELETING,              ST_HUMAN_REVIEW_REQUIRED)  # Fehler → zurück zum Gate
(ST_DELETE_APPROVED,       ST_HUMAN_REVIEW_REQUIRED)  # Revoke/Fehler
```

**Keine Änderung** an `_HUMAN_GATE_OPS`, `RC_AMBIGUOUS_DELETE`, oder den bestehenden
Transitions. Der bestehende `OP_DELETE_REQUEST → HUMAN_REVIEW_REQUIRED`-Pfad bleibt
unverändert.

---

## 10. CLI CHANGES

Neue Befehle in `rq_c5_cli.py`:

- `c5-delete approve --commit <sha> --object-id <id> --path <path>` → persistiert Approval (NUR Approval)
- `c5-delete execute --commit <sha>` → führt DELETE aus (verlangt persistierte Approval)
- `c5-delete status --commit <sha>` → read-only Status
- `c5-delete replay --commit <sha>` → idempotenter Replay nach Crash

**Kein undifferenzierter approve+delete-Blackbox-Befehl.**

---

## 11. SECURITY REVIEW (Design-Zusicherungen)

- **Keine arbitrary path deletion:** Executor nimmt `path` nur aus dem ObjectChange, das durch Approval gebunden ist.
- **Keine path traversal:** `path` wird gegen `VAULT_PREFIX` validiert.
- **Keine ungeprüften freien Delete-Targets:** Kein freier Pfad-Parameter im Executor.
- **Keine Approval-Reuse:** `approval_id` eindeutig; nach Nutzung → `USED`.
- **Keine Cross-Commit-Approval:** Approval bindet `workflow_commit`.
- **Keine Cross-Object-Approval:** Approval bindet `object_id` + `path`.
- **Keine automatische Approval-Eskalation:** Nur expliziter CLI-Befehl erzeugt Approval.
- **Keine Secrets:** Approval speichert keine Credentials/personenbezogenen Daten.
- **Keine Credential-Ausgabe:** Kein Secret im Approval-/Status-Output.
- **Keine manuelle DB-Manipulation:** Nur Store-Methoden.
- **Keine allgemeine DELETE-Automatisierung:** Kein Pfad führt DELETE ohne Approval.

---

## 12. TESTPLAN (mindestens)

- DELETE ohne Human Approval → BLOCKED
- DELETE mit Approval für anderes Objekt → BLOCKED
- DELETE mit Approval für anderen Commit → BLOCKED
- manipulierte object_id → BLOCKED
- manipulierter path → BLOCKED
- gültiges Approval → exakt ein DELETE
- anderes Objekt bleibt unverändert
- DELETE_ALREADY_AT_TARGET → kein zweiter destruktiver Write
- Restart nach Approval → Approval erhalten
- Crash nach DELETE → Replay sicher
- Search Exact-Set nach DELETE
- Search-Mismatch → kein APPLIED
- Secret Safety
- keine SQL-/State-Bypässe
- bestehende WRITE-/UPDATE-Flows ohne Regression
- HUMAN_REVIEW_REQUIRED bleibt Default für neue DELETE requests
- keine automatische Approval-Erzeugung
- Multi-Commit-Test: Approval A darf DELETE B niemals autorisieren

---

## 13. INCIDENT LESSON (verbindlich, bleibt)

```
INCIDENT_OCCURRED = TRUE
INCIDENT_RECOVERED = TRUE
PERMANENT_DAMAGE = NONE VERIFIED
ROOT_CAUSE = unsafe mutating endpoint probe during read-only discovery
```

**Neue verbindliche Regel:** `NO MUTATING HTTP METHOD PROBES DURING PRODUCTION READ-ONLY
DISCOVERY`. Diese Regel darf durch die neue DELETE-Implementierung NICHT aufgeweicht werden.

---

## 14. HARD STOP

Nach erfolgreicher Implementation, Tests, Push und Fresh Checker: **STOPP.**
KEIN realer Canary-Delete. KEIN produktiver Search-Rebuild. KEIN C5F-Cleanup. KEIN C5G.
KEINE Netzwerkänderung. KEINE Hermes-Rechte. KEINE Hermes-Autonomie.
Christian erteilt danach separat die Freigabe zur produktiven Canary-Cleanup-Validierung.