v1.6.0

2026-09-02 10:26:50 +02:00
parent 8c4ce2d6c2
commit 9a4370e4df
272 changed files with 31244 additions and 5980 deletions
@@ -200,3 +200,7 @@ Die beiden Evidenzklassen werden absichtlich nicht vermischt. Outcome-Memories l
 Für source-begrenzte Exact-Fallbacks hält der Store einen rebuildbaren In-Memory-Index `Provenance.Source -> Memory IDs`. Damit wächst der Fallback mit der betreffenden Integration/Source statt mit dem gesamten Memory-Katalog. HNSW/Disk-PQ bleiben globale Kandidatenindizes.

 Die Qualitätsmessung ist vom Schreibpfad getrennt: `/api/quality/replay` ist read-only und evaluiert live die aktuelle Knowledge-/Outcome-Retrieval-Konfiguration gegen einen bereitgestellten historischen Fallkorpus.
+
+## v1.6.0 Master/Subagent consistency model
+
+NeuroForge owns the authoritative durable state. Subagents are stateless executors: they register capabilities, claim only compatible jobs and return lease-fenced results. Jobs and second-phase master applies are persisted through the normal WAL/checkpoint path, so restarts do not lose queued/retrying/apply-wait work. The graph backfill uses ANN candidate selection plus bounded exact relink jobs; pairwise synapses form an n:m adjacency graph and retrieval can traverse several bounded hops. See `MASTER-SUBAGENT-ORCHESTRATOR.md`.
@@ -46,3 +46,7 @@ Die eigentlichen Laufzeitmetriken und Einzelfall-Evidenzen bleiben beim Agenten
 ## v1.4 Unified Graph Explorer

 The Control Center remains read-only. Its graph views use a dedicated Agent `CONTROL_READ_TOKEN` and the scoped NeuroForge app key. The Engineering Graph is embedded from a reproducible Go AST/Compose snapshot; optional Codebase Memory MCP is developer-only. See `UNIFIED-GRAPH.md`.
+
+## v1.6.0 Orchestrator / Knowledge Graph
+
+The read-only Control Center queries scoped NeuroForge endpoints for scheduler and graph state. It displays leader/follower role, online/stale subagents, queue states (`queued`, `claimed`, `retry_wait`, `blocked`, `apply_wait`, `failed`) and graph connectivity (`isolated`, `linked`, `multi_linked`, average/max degree, components). Administrative retry/cancel/backfill actions remain on the separately authenticated NeuroForge admin API and are not exposed by Control Center.
@@ -121,3 +121,9 @@ The synthesis call, syntax repair and grounding rewrite use `NEUROFORGE_KB_STAGI
 Claim verification checks all material article statements in batches of `NEUROFORGE_KB_STAGING_MAX_VERIFICATION_STATEMENTS`; the value is a batch size, not a total verification cap. A hard safety ceiling of 128 material statements remains. Staging persists `article_quality` with actual article/answer lengths, configured bounds, evidence count, prompt size, expansion status and synthesis token usage.

 Fortinet `support-forum` pages are treated as vendor-community evidence rather than authoritative primary documentation. Editorial `technical-tip` and `troubleshooting-tip` pages remain eligible as authoritative first-party material.
+
+### Master/Subagent Orchestrator & Knowledge Graph (v1.6.0)
+
+The master scheduler is controlled by `NEUROFORGE_WORKER_LEASE_SECONDS`, `NEUROFORGE_WORKER_HEARTBEAT_SECONDS`, `NEUROFORGE_WORKER_STALE_AFTER_SECONDS`, retry/backoff/queue/retention settings, and the graph-backfill limits shown in `.env.example`. Local workers use `NEUROFORGE_CPU_WORKER_CONCURRENCY` / `NEUROFORGE_GPU_WORKER_CONCURRENCY`; remote workers use `docker-compose.subagent.yml` with a reachable `NEUROFORGE_MASTER_URL` and unique `NEUROFORGE_CPU_WORKER_ID` / `NEUROFORGE_GPU_WORKER_ID`.
+
+`NEUROFORGE_OFFLOAD_CHAT` and `NEUROFORGE_OFFLOAD_EMBEDDINGS` prefer a live capability-compatible GPU subagent. If no compatible live subagent is available, NeuroForge continues through its normal provider router. Graph convergence is bounded by `NEUROFORGE_GRAPH_BACKFILL_BATCH_SIZE`, `NEUROFORGE_GRAPH_BACKFILL_MAX_QUEUED`, `NEUROFORGE_GRAPH_BACKFILL_MIN_DEGREE`, `NEUROFORGE_GRAPH_CANDIDATE_MULTIPLIER` and the retry cooldown. Multi-hop retrieval is bounded by `NEUROFORGE_GRAPH_MAX_HOPS`, `NEUROFORGE_GRAPH_HOP_DECAY`, `NEUROFORGE_GRAPH_MAX_EXPANSION` and `NEUROFORGE_GRAPH_MIN_EDGE_WEIGHT`.
@@ -26,6 +26,13 @@
 - lokales Outcome-Audit mit `pending|learned|failed`, Retry und unveränderlicher Revisionskette
 - Stale-Run-Schutz gegen Lernen aus überholten GLPI-Ticketzuständen
 - getrennte Schalter für Research/SearXNG und zeitgesteuerte Autonomie
+- persistenter Master/Subagent-Orchestrator mit Resource-/Capability-Routing, Priorität, DAG-Dependencies, Retry/Backoff und Idempotenz
+- Heartbeat/Lease-Fencing inklusive Expiry-Prüfung und stale-result Schutz
+- zweiphasiger `apply_wait`-Commit für Worker-Ergebnisse, die autoritativen Master-State verändern
+- CPU-Subagents für `vector.relink`, GPU-Subagents für `model.chat`/`model.embed`, optional remote über `docker-compose.subagent.yml`
+- bounded Knowledge-Graph-Backfill für importierte Memories (ANN-Kandidaten statt O(N²))
+- echte n:m-Adjamenz, Relationstypen, Multi-Hop-Retrieval und Graph-Health-Metriken
+- Memory-Version + Vector-Fingerprint-Fencing gegen Delete/Recreate-Races während Relink

 ## Bewusst nicht automatisiert

@@ -0,0 +1,144 @@
+# NeuroForge Master / Subagent Orchestrator (v1.6.0)
+
+## Zielbild
+
+NeuroForge ist der autoritative **Master/Orchestrator**. Subagents besitzen keinen eigenen autoritativen Knowledge-State. Sie registrieren sich mit Resource-Class und Capabilities, ziehen passende Jobs und liefern Ergebnisse unter Lease-Fencing zurück.
+
+```text
+                         durable WAL/checkpoint
+                                │
+                       ┌────────▼────────┐
+                       │ NeuroForge      │
+                       │ Master          │
+                       │ scheduler + DAG │
+                       └───────┬─────────┘
+                  capability /│\ lease-fenced jobs
+                             / │ \
+                ┌───────────┐  │  ┌─────────────┐
+                │ CPU agent │  │  │ GPU agent   │
+                │ relinking │  │  │ chat/embed  │
+                └───────────┘  │  └─────────────┘
+                               │
+                         more subagents
+```
+
+## Konsistenzmodell
+
+- Jobs sind persistent; Queue, Retry, Dependencies und Worker-Ergebnis überleben einen Master-Neustart.
+- Jeder Claim erhält ein eindeutiges `lease_token`. Eine verspätete Antwort einer abgelaufenen Lease wird auch dann abgewiesen, wenn der Job noch nicht neu vergeben wurde; nach Reclaim verhindert der neue Token zusätzlich stale writes.
+- Heartbeats verlängern nur aktive, zum Worker passende Leases.
+- Fehler werden exponentiell mit begrenztem Backoff wiederholt; `max_attempts` verhindert Endlosschleifen.
+- Abhängigkeiten (`depends_on`) bilden einen DAG: Child-Jobs bleiben `blocked`, bis alle Parents `done` sind. Ein terminal fehlgeschlagener Parent lässt das Child fail-closed scheitern.
+- Worker-Ergebnisse, die autoritativen Master-State verändern (`vector.relink`), verwenden eine zweite persistente Phase `apply_wait`. Der Ergebnisblob ist bereits geschrieben, bevor der Master ihn anwendet. Master-Apply wird idempotent wiederholt und erst danach wird der Job `done`.
+- Terminale Job-Historie wird nach Retention/Cap bereinigt; noch referenzierte Dependency-Jobs werden erhalten.
+- In Clusterbetrieb plant und appliziert nur der aktuelle NeuroForge-Leader. Standalone ist der einzelne Master autoritativ.
+
+## Resource-/Capability-Routing
+
+Aktuelle Standardtypen:
+
+| Job | Resource | Capabilities | Wirkung |
+|---|---|---|---|
+| `vector.relink` | CPU | `cpu,vector.relink` | ANN-Kandidaten exakt nachbewerten, n:m-Synapsen liefern |
+| `model.embed` | GPU | `gpu,model.embed` | Embedding über den GPU-Subagent/Ollama |
+| `model.chat` | GPU | `gpu,model.chat` | Chat/Structured Output über den GPU-Subagent/Ollama |
+
+Ein Worker kann zusätzliche Capabilities deklarieren. Ein Job wird nur an einen Worker vergeben, der **alle** verlangten Capabilities besitzt und unter seinem `max_concurrency` liegt.
+
+## Knowledge-Graph statt 1:1
+
+Eine Graphdatenbank besteht intern weiterhin aus paarweisen Kanten. Entscheidend für einen echten Graphen ist, dass ein Knoten mehrere Kanten besitzen kann und Traversierung mehrere Hops folgt. v1.6.0 stellt beides sicher:
+
+- `vector.relink` verbindet einen Memory-Knoten mit mehreren ANN-Nachbarn (`RecallK`).
+- `GraphBackfillMinDegree` erzwingt für geeignete Memories einen Mindestgrad statt einer einzigen Partnerkante.
+- `synapseAdj` hält eine echte Adjazenzliste und verhindert O(E)-Scans pro Hop.
+- Retrieval propagiert bounded über `GraphMaxHops` Hops mit `GraphHopDecay`.
+- Kanten tragen `relations[]`, z.B. `semantic_similarity`, `association`, `coactivation`.
+- `GraphStats` misst `multi_linked_memories`, Max-/Durchschnittsgrad, Connected Components und Largest Component. Damit ist n:m-Verkettung objektiv prüfbar.
+
+Der aktuelle automatische Backfill erzeugt primär **assoziative/semantische** Beziehungen. Das ist ein Wissensgraph im graphentheoretischen Sinn, aber noch keine vollständig ontologische Aussagenlogik wie `causes`, `solves`, `depends_on`. Solche Relationstypen können später kontrolliert ergänzt werden, ohne das n:m-/Multi-Hop-Fundament zu ändern.
+
+## Bulk-Backfill für große Knowledge-Bestände
+
+Der Master legt **nicht** alle möglichen Paare als O(N²)-Jobs an. Für jeden Kandidaten wird zuerst der ANN-Index verwendet; nur eine begrenzte Menge Vektoren wird in einen `vector.relink`-Job geschrieben.
+
+Wichtige Limits:
+
+```env
+NEUROFORGE_GRAPH_BACKFILL_BATCH_SIZE=64
+NEUROFORGE_GRAPH_BACKFILL_MAX_QUEUED=256
+NEUROFORGE_GRAPH_BACKFILL_MIN_DEGREE=3
+NEUROFORGE_GRAPH_CANDIDATE_MULTIPLIER=6
+NEUROFORGE_GRAPH_RETRY_AFTER_MINUTES=360
+```
+
+Bereits wartende Targets werden bei der nächsten Planung übersprungen, damit ein großer Korpus nicht durch die lexikographisch ersten IDs verhungert.
+
+## Monitoring
+
+Read-only Control-API:
+
+```text
+GET /api/v1/integrations/orchestrator/status
+GET /api/v1/integrations/graph/status
+```
+
+Admin-API:
+
+```text
+GET  /admin/api/orchestrator/status
+GET  /admin/api/orchestrator/jobs
+POST /admin/api/orchestrator/jobs/{id}/retry
+POST /admin/api/orchestrator/jobs/{id}/cancel
+GET  /admin/api/graph/status
+POST /admin/api/graph/backfill
+```
+
+Prometheus enthält u.a.:
+
+```text
+neuroforge_jobs{status="queued|claimed|retry_wait|blocked|apply_wait|done|failed|canceled"}
+neuroforge_workers{resource="cpu|gpu",status="online|stale"}
+neuroforge_worker_inflight{worker="...",resource="..."}
+neuroforge_worker_capacity{worker="...",resource="..."}
+neuroforge_graph_memories{state="linked|isolated|multi_linked"}
+neuroforge_graph_max_degree
+neuroforge_graph_average_degree
+neuroforge_graph_connected_components
+neuroforge_graph_largest_component
+```
+
+## Remote Subagent
+
+Auf einem zusätzlichen Host nur `docker-compose.subagent.yml` und eine kleine `.env` bereitstellen. Beispiel GPU:
+
+```env
+IMAGE_TAG=1.6.0
+NEUROFORGE_MASTER_URL=https://neuroforge.internal.example
+NEUROFORGE_WORKER_TOKEN=<shared-worker-token>
+NEUROFORGE_GPU_WORKER_ID=gpu-node-02
+NEUROFORGE_WORKER_OLLAMA_URL=http://127.0.0.1:11434
+OLLAMA_MODEL=gemma4
+OLLAMA_EMBEDDING_MODEL=embeddinggemma
+NEUROFORGE_GPU_WORKER_CONCURRENCY=1
+```
+
+Dann:
+
+```bash
+docker compose -f docker-compose.subagent.yml --profile gpu up -d
+```
+
+Der Master-Port muss vom Subagent erreichbar sein. Für Netze außerhalb eines vertrauenswürdigen internen Segments gehört TLS/mTLS vor den Master-Endpunkt (Reverse Proxy/Service Mesh). Der Worker-Token ist ein Service-Credential und muss separat von App/Admin/Integration-Tokens bleiben.
+
+## Operationaler Zielzustand
+
+Ein gesunder Zustand hat:
+
+- mindestens einen `online` CPU-Worker für Graph-Konvergenz,
+- optional mindestens einen `online` GPU-Worker für Offload,
+- keine dauerhaft wachsende `failed`-/`apply_wait`-Queue,
+- sinkende Zahl `isolated` und steigende Zahl `multi_linked`,
+- `max_degree > 1` und `largest_component > 1`,
+- bounded Queue und stabile Worker-Leases,
+- keine Readiness-Abhängigkeit des Masters vom Worker (verhindert Startup-Deadlocks).
@@ -0,0 +1,28 @@
+# Migration v1.5.9 → v1.6.0
+
+Die Migration ist **nicht destruktiv**. Keine Volumes, Knowledge-Dateien, Memories, Goals oder Staging-Drafts löschen.
+
+1. v1.6.0 Images bauen/publizieren.
+2. `IMAGE_TAG=1.6.0` setzen.
+3. Die neuen Orchestrator-/Graph-Variablen aus `.env.example` übernehmen. Die Defaults sind produktionsnah und bounded.
+4. Den bisherigen einzelnen `neuroforge-worker` durch `neuroforge-worker-cpu` und `neuroforge-worker-gpu` ersetzen.
+5. Stack neu erzeugen; Volumes beibehalten.
+
+```bash
+docker compose --profile research pull
+docker compose --profile research up -d --force-recreate --remove-orphans
+```
+
+Danach prüfen:
+
+```bash
+docker compose ps
+curl -s -H "Authorization: Bearer $NEUROFORGE_CONTROL_READ_TOKEN" \
+  http://127.0.0.1:${NEUROFORGE_HOST_PORT:-8090}/api/v1/integrations/orchestrator/status | jq
+curl -s -H "Authorization: Bearer $NEUROFORGE_CONTROL_READ_TOKEN" \
+  http://127.0.0.1:${NEUROFORGE_HOST_PORT:-8090}/api/v1/integrations/graph/status | jq
+```
+
+Ein gesunder Zustand hat mindestens einen online CPU-Worker, keine dauerhaft wachsende `failed`/`apply_wait` Queue und eine sinkende Zahl isolierter Memories. GPU-Offload ist optional; ohne online GPU-Subagent fällt NeuroForge auf den normalen Provider-Router zurück.
+
+Remote Subagents erhalten eindeutige `NEUROFORGE_CPU_WORKER_ID` bzw. `NEUROFORGE_GPU_WORKER_ID`. Außerhalb eines vertrauenswürdigen internen Netzes den Master nur hinter TLS/mTLS veröffentlichen.
@@ -0,0 +1,32 @@
+# GLPI NeuroForge Mega v1.6.0
+
+v1.6.0 erweitert NeuroForge von einem einzelnen Workerpfad zu einem dauerhaften Master/Subagent-Orchestrator und schließt die Graph-Lücke großer Knowledge-Imports.
+
+## Orchestrator
+
+- persistente Jobs im NeuroForge-WAL/Checkpoint
+- Resource-Class + Capability-Routing (`cpu`, `gpu`, `vector.relink`, `model.chat`, `model.embed`)
+- Priorität, Idempotency-Key, Parent/Dependencies, Retry mit begrenztem Backoff und Max-Attempts
+- Heartbeats, Worker-Staleness, Max-Concurrency und lease-token fencing
+- abgelaufene Leases werden auch dann abgewiesen, wenn noch kein anderer Worker den Job übernommen hat
+- Worker-Ergebnisse mit Master-Mutation verwenden `apply_wait`: Resultat zuerst persistent, danach idempotenter Master-Apply
+- Apply-Retries überleben Neustarts; terminale Jobhistorie wird bounded bereinigt
+- Admin-Status, Jobliste, Retry, Cancel und manueller Graph-Backfill
+
+## Knowledge Graph
+
+- importierte `knowledge.chunk`-Memories werden bounded nachverknüpft
+- ANN bestimmt nur Kandidaten; CPU-Subagents führen exakte Similarity-Bewertung aus
+- ein Memory kann mehrere Edges besitzen; `GraphBackfillMinDegree` verhindert den früher praktisch isolierten/1:1-artigen Zustand
+- Adjazenzindex + bounded Multi-Hop-Retrieval mit Hop-Decay
+- Synapsen können mehrere `relations[]` tragen
+- Graphmetriken: linked/isolated/multi-linked, average/max degree, connected components, largest component
+- Relink-Payload bindet Target und Kandidaten an Version + Vector-Fingerprint; veraltete Delete/Recreate-Ergebnisse werden verworfen
+
+## Deployment
+
+Der lokale Stack enthält getrennte CPU- und GPU-Subagents. Zusätzliche Hosts verwenden `docker-compose.subagent.yml`. Für Remote-Netze ist TLS/mTLS vor dem Master-Endpunkt erforderlich; der Worker-Token bleibt ein separates Service-Credential.
+
+## Compatibility
+
+Die Migration ist nicht destruktiv. Bestehende Memories/Knowledge/Goals bleiben erhalten. Nach dem Upgrade beginnt der Graph-Backfill kontrolliert im Hintergrund; deshalb können `neuroforge_synapses` und die Graph-Connectivity-Metriken nach und nach steigen.