mindnet/docs/99_Archive/WP15c_merge_commit.md

Branch Merge Commit Message: WP15c

feat: Multigraph-Support, Diversity Engine & Provenance Firewall (v2.9.1)

## Graph Topology & Edge Management (WP-15c)

### Section-Präzision & Multigraph-Modus
- Präzise Erkennung von Obsidian-Ankern (`[[Note#Section]]`) und Self-Links (`[[#Section]]`)
- Links werden in `target_id="Note"` und `target_section="Section"` aufgelöst
- Edge-ID enthält `variant` (Section) für eindeutige Identifikation
- Multigraph-Modus: Mehrere Kanten zwischen denselben Notizen möglich, wenn sie auf verschiedene Sections zeigen
- Behebt "Phantom-Knoten" durch korrekte Trennung von Note-Name und Abschnitt

**Geänderte Dateien:**
- `app/core/graph/graph_utils.py`: `parse_link_target()` für Section-Extraktion & Self-Links (v1.1.2)
- `app/core/graph/graph_derive_edges.py`: Multigraph-Support, `target_section` in Edge-Payload (v1.1.2)
- `app/core/graph/graph_subgraph.py`: Metadaten-Persistenz (v1.2.0)
- `app/core/graph/graph_db_adapter.py`: Vollständige Metadaten-Durchreichung (v1.1.1)

### Provenance Firewall (Edge Registry v0.8.0)
- System-Kanten (`next`, `prev`, `belongs_to`) dürfen nur mit `provenance="structure"` gesetzt werden
- Alle anderen Provenienzen (`explicit`, `semantic_ai`, `inherited`, `global_pool`, `rule`) werden blockiert
- Automatischer Fallback auf `related_to` bei unerlaubter Verwendung
- Logging in `data/logs/unknown_edges.jsonl` für Admin-Review

**Geänderte Dateien:**
- `app/services/edge_registry.py`: Provenance Firewall (v0.8.0)

## Retrieval-Intelligenz (The Diversity Engine)

### Note-Level Diversity Pooling
- Pro `note_id` wird nur der relevanteste Treffer im Endergebnis behalten
- Verhindert "Note-Flooding" (Dominanz einer einzigen Notiz durch viele ähnliche Chunks)
- Workflow: Sortierung nach finalem Score → Diversity-Pooling → Begrenzung auf `top_k`

**Geänderte Dateien:**
- `app/core/retrieval/retriever.py`: Note-Level Diversity Pooling (v0.7.0)

### Super-Edge Aggregation
- Parallele Kanten zwischen zwei Notizen werden mathematisch zu einer "Super-Edge" aggregiert
- Primäre Kante zählt voll, weitere Kanten werden mit Dämpfungsfaktor **0.1** gewichtet
- Verhindert Score-Explosionen durch multiple Links auf verschiedene Sections
- Metadaten: `is_super_edge` Flag und `edge_count` für Explanation Layer

**Geänderte Dateien:**
- `app/core/retrieval/retriever.py`: Super-Edge Aggregation (v0.7.0)

### Metadaten-Persistenz
- In-Memory Subgraph und Datenbank-Adapter erweitert für durchgängige Metadaten-Erhaltung
- `target_section`, `provenance` und `confidence` werden vollständig erhalten
- Ermöglicht präzises Retrieval-Reasoning und Explanation Layer

**Geänderte Dateien:**
- `app/core/graph/graph_subgraph.py`: Metadaten-Persistenz (v1.2.0)
- `app/core/graph/graph_db_adapter.py`: Vollständige Metadaten-Durchreichung (v1.1.1)

## Mathematisches Scoring (WP-22 Integration)

### Hybrid Scoring Formula (v1.0.3)
- Neue Formel: `Final = (Semantic * StatusMult) * (1 + TypeBoost + EdgeBonus + CentBonus)`
- Status-Gatekeeper: `stable` = 1.2, `draft` = 0.5, `active` = 1.0
- Graph Boost Factor: Intent-spezifische Verstärkung (1.5x bei aktivem Intent)
- Status wirkt als Multiplikator auf die Basis-Relevanz, Graph-Boni werden proportional verstärkt

**Geänderte Dateien:**
- `app/core/retrieval/retriever_scoring.py`: Hybrid Scoring Formula (v1.0.3)

### Explanation Layer
- Detaillierte Begründungen für jeden Bonus (Sektions-Links, Hub-Zentralität, Super-Edge-Informationen)
- Provenance-Informationen für erhöhte Transparenz
- Massiv erhöhte Transparenz für Debugging und Nutzer-Vertrauen

**Geänderte Dateien:**
- `app/core/retrieval/retriever.py`: Explanation Layer (v0.7.0)

## Ingestion & Profil-Synchronisation

### Registry-First Profiling (v2.13.12)
- Hierarchische Auflösung: Frontmatter > types.yaml Typ-Config > Global Defaults
- Konsistente Verarbeitung je nach Notiz-Typ
- Note-Typen wie `value` erhalten automatisch das korrekte Profil (`structured_smart_edges_strict`)

**Geänderte Dateien:**
- `app/core/ingestion/ingestion_processor.py`: Registry-First Profiling (v2.13.12)

## Impact & Breaking Changes

### Keine Migration erforderlich
**WICHTIG:** Diese Version ist **rückwärtskompatibel**. Bestehende Vaults funktionieren ohne Re-Import.

**Empfehlung:** Optionaler Re-Import für optimale Nutzung der neuen Features:
```bash
python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force

Fixes

• ✅ Resolves: "Phantom-Knoten" durch korrekte Trennung von Note-Name und Section
• ✅ Resolves: Score-Explosionen durch multiple Links auf verschiedene Sections
• ✅ Resolves: "Note-Flooding" durch fehlende Diversity-Filterung
• ✅ Resolves: Inkonsistente Metadaten durch fehlende Persistenz im Subgraph
• ✅ Resolves: Manipulation von System-Kanten durch Provenance Firewall

Dokumentation

Alle relevanten Dokumente aktualisiert:

• 02_concept_graph_logic.md: Provenance Firewall, Self-Links, Multigraph-Support
• 03_tech_retrieval_scoring.md: Hybrid Scoring Formula, Note-Level Diversity, Super-Edge Aggregation
• 03_tech_data_model.md: Section-Support, Metadaten-Persistenz
• 03_tech_ingestion_pipeline.md: Registry-First Profiling (bereits dokumentiert)

Versionen

• Edge Registry: v0.8.0
• Graph Utils / Derive Edges: v1.1.2
• Graph Subgraph: v1.2.0
• Graph DB Adapter: v1.1.1
• Retriever: v0.7.0
• Retriever Scoring: v1.0.3
• Ingestion Processor: v2.13.12

Closes #[issue-number]