diff --git a/tolaria/c4b-search-service/DEPLOYMENT_PLAN.md b/tolaria/c4b-search-service/DEPLOYMENT_PLAN.md new file mode 100644 index 0000000..877c1f8 --- /dev/null +++ b/tolaria/c4b-search-service/DEPLOYMENT_PLAN.md @@ -0,0 +1,116 @@ +# C4 SEARCH v1 — PRODUCTION DEPLOYMENT PLAN (PLAN ONLY — NICHT deployt) + +**Phase:** C4 SEARCH v1 (Acceptance Preparation) +**Status:** PLAN / ACCEPTANCE READY — **PRODUCTION_DEPLOYMENT = NOT_DEPLOYED** +**Gültig:** 2026-08-26 · Entscheidung: Tolaria v1 = EXACT + KEYWORD + METADATA (kein Semantic/Vector/pgvector/Embedding) + +> ⚠️ Dies ist ein **Plan**. Es wird nichts deployt, kein Container gebaut/gestartet, +> kein C5 gestartet, keine Hermes-Autonomisierung. Ausführung erfordert später eine +> autorisierte Freigabe und einen freigegebenen Executor. + +--- + +## 0. Kurzstatus (Ist) + +| Metrik | Wert | +|---|---| +| IMPLEMENTATION_STATUS | COMPLETE | +| TEST_RUNTIME_STATUS | PASS (22/22 Corpus v1.1; Quality MRR 0.8, Recall@5/10 0.8, canonical-hit 1.0, hist-error 0.0) | +| PRODUCTION_DEPLOYMENT_STATUS | **NOT_DEPLOYED** | +| SUPPORTED_MODES | `exact`, `keyword`, `metadata` | +| UNSUPPORTED (ehrlich) | `semantic`, `vector`, `hybrid` → `mode_not_implemented` | +| C4B Commit | `main@aad56a2` | +| Ollama qwen3-embedding | **ENTFERNT** (2026-08-26, ONLY_USED_BY_C4C, Christian-Freigabe) | + +--- + +## 1. Produktives Zielbild (empfohlene Architektur, §7) + +**Eigener kleiner Container / Service** für den TOLARIA SEARCH SERVICE. +- **NICHT** eingebaut in: Trading-System-Module, Forgejo, Tolaria-Rust/Tauri-Container. +- Search bleibt eine **eigene Failure Domain**: Ausfall des Search-Service darf Forgejo/Tolaria/Trading nicht beeinträchtigen und umgekehrt. +- Service ist **ausschließlich intern erreichbar** (private Docker-Netz / localhost / internes Bridge-Netz). **Keine öffentliche Exposition ohne Notwendigkeit.** Kein Reverse-Proxy für externen Zugriff, solange kein Bedarf dokumentiert ist. + +### Netzwerk-Topologie (geplant) +``` +[Docker internes Bridge-Netz "tolaria_search"] + | + |--- search-service (Container, stdlib python, Port 8325) + | - /api/search (POST+GET, read-only) + | - /api/search/health + | - /api/search/rebuild (Auth: Bearer TOLARIA_SEARCH_REBUILD_TOKEN) + | + (Zugriff nur aus demselben Netz; Host-Port nicht nach außen exponieren) +``` + +--- + +## 2. Anforderungs-Checkliste (Deployment-Gap, §6) + +| Anforderung | Bewertung | Details | +|---|---|---| +| **Executor** | benötigt | autorisierter Executor mit VPS-/Docker-Zugang (Red Queen via legitimer Weg; kein Root-SSH ohne Gate). Mindestens Host-Docker-Client. | +| **Host-/Docker-Zugang** | benötigt | Docker-Daemon am VPS (`187.124.31.123`). Kein Daemon aus dem Hermes-Sandbox-Context direkt — Zugang über SSH-Gate/executor. | +| **Container/Service-Bedarf** | 1 kleiner Container | stdlib-only Python; kein Build von externen Abhängigkeiten; Image minimal (python:3.11-slim o.ä.) oder direkt `python3 server.py`. | +| **Persistenzbedarf** | minimal, DERIVED | nur `data/search_index.json` (ableitbar) + ggf. Index-Source. **Kein Zustand, der nicht rebuildbar ist.** Kein Volume mit kritischen Daten. | +| **Port / interne Erreichbarkeit** | `8325` intern | `TOLARIA_SEARCH_PORT`; nur im internen Netz erreichbar. Nicht auf 0.0.0.0 des Hosts nach außen pinnen. | +| **Health Endpoint** | vorhanden | `GET /api/search/health` (gibt supported_modes, object_count, source_head). Nutzen als Docker-Healthcheck. | +| **Restart Policy** | `unless-stopped` o.ä. | kleiner stateless Rebuildable-Service; Neustart unkritisch (lädt Index aus `data/` oder rebuildet). | +| **Ressourcenbedarf** | niedrig | stdlib-only, in-memory Index (84 Objekte). <256MB RAM, <1 CPU. Latency gemessen P95 <5ms. | +| **Netzwerk** | intern | eigenes Docker-Network (z. B. `tolaria_search`). Kein Host-Port-Mapping nach außen. | +| **Reverse Proxy** | **nicht nötig** | solange nur intern von Agents genutzt. Falls später extern: erst Freigabe + Auth-Gateway. | +| **Agent Access** | READ-ONLY API | nur `/api/search` (POST/GET). Kein Rebuild für normale Agents. | +| **Backup/Rebuild** | Rebuild-basiert | `rebuild.py --source index_source.json` aus Forgejo-Source (C5-Trigger). Kein separates Backup des Index nötig (derived). | +| **Rollback** | Container-Neu-Deploy | alten Image/Compose wieder anheben; Daten bleiben rebuildbar. Kein Daten-Risiko. | +| **Secret Handling** | über Env | `TOLARIA_SEARCH_REBUILD_TOKEN` ephemer als Container-Env/Secret, nie im Repo. Credentials nie dokumentieren. | + +--- + +## 3. Agent Access Plan (§8) + +**Prinzip:** READ-ONLY Search API. Keine Knowledge-Mutation über Search. + +| Agent | Zugriff | Methode | +|---|---|---| +| Red Queen | READ-ONLY Suche | `GET/POST /api/search` aus internem Netz | +| Hermes | READ-ONLY Suche | dito (wenn im selben Netz) | +| Rain | READ-ONLY Suche | dito | +| Alice | READ-ONLY Suche | dito | +| alle | **KEIN** `/api/search/rebuild` | Rebuild nur über zentralen Token/Executor | + +- **Keine Admin-/Rebuild-Endpunkte offen für normale Agents.** Rebuild nur mit + `TOLARIA_SEARCH_REBUILD_TOKEN` (Bearer) — nur autorisierter Pfad (C5/Operator). + +--- + +## 3. C5 HANDOFF — Trigger-Spezifikation (§9) + +C5 = Forgejo→Tolaria-Sync/Index-Aktualisierung. **Keine Embedding-/Vector-Logik mehr.** + +| Ereignis | C5-Aktion | +|---|---| +| NEW OBJECT | Keyword/Metadata-Index inkrementell aktualisieren oder kontrollierten Rebuild auslösen | +| CONTENT CHANGE | Object neu tokenisieren/rankable update; content_hash ersetzen | +| METADATA CHANGE | Metadata-Felder (type/role/representation/state/tags/aliases) neu indizieren | +| STATE CHANGE | current/historical-Flags, canonical-Rang aktualisieren | +| RENAME / MOVE | path/aliases/title im Index aktualisieren, Alt-Lookups erhalten | +| DELETE / SUPERSEDE | Object aus Index entfernen bzw. auf Nachfolger/current umschlagen | + +- Rebuild-Eintrittspunkt: `POST /api/search/rebuild` mit Bearer-Token ODER lokale `rebuild.py`. +- C5 läuft **nicht autonom**; wird nur mit Freigabe und korrektem Write-Pfad (Forgejo-Master→Verify→Search-Propagation) gestartet. +- **Keine Embedding-/Vector-/pgvector-Logik.** + +--- + +## 4. Offene Punkte / Freigaben + +- **AUTORISIERTER EXECUTOR** für den tatsächlichen Deploy muss benannt/freigegeben werden. +- **Host-/Docker-Zugang** für den Executor legitimieren. +- **Deployment** selbst erst nach expliziter Freigabe ausführen (diese Mission deployt NICHT). +- Reverse Proxy nur falls später extern nötig — vorher Freigabe + Auth-Gateway. + +--- + +## 5. Fazit + +Search v1 ist **ACCEPTANCE READY**. Produktions-Deployment ist geplant, aber **NICHT ausgeführt**. C5 ist spezifiziert (Keyword/Metadata-Rebuild), aber **NICHT gestartet**. Hermes-Autonomisierung **NICHT gestartet**.