docs(tolaria): add C4 Search v1 production deployment plan (C4B)
This commit is contained in:
parent
aad56a26ea
commit
29cbca9357
1 changed files with 116 additions and 0 deletions
116
tolaria/c4b-search-service/DEPLOYMENT_PLAN.md
Normal file
116
tolaria/c4b-search-service/DEPLOYMENT_PLAN.md
Normal file
|
|
@ -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**.
|
||||
Loading…
Reference in a new issue