mindnet/docs/99_Archive/WP4d_release_notes.md

# Release Notes: Mindnet v2.9.1 (WP4d)

**Release Date:** 2025-01-XX  
**Type:** Feature Release mit Breaking Changes  
**Branch:** WP4d

---

## 🎯 Übersicht

Diese Version führt **Section-basierte Links** ein, verbessert das Chunking durch **Atomic Section Logic** und implementiert **Registry-First Profiling** für konsistentere Konfigurationsauflösung. Die Änderungen erfordern einen **vollständigen Re-Import** bestehender Vaults.

---

## ✨ Neue Features

### Section-basierte Links (Deep-Links)

Mindnet unterstützt nun **Deep-Links** zu spezifischen Abschnitten innerhalb einer Note:

```markdown
[[rel:based_on Mein Leitbild#P3 – Disziplin]]
```

**Vorteile:**
- Mehrere Links zur gleichen Note möglich (verschiedene Sections)
- Präzise Kontext-Ladung (nur relevanter Abschnitt)
- Keine "Phantom-Knoten" mehr durch korrekte Trennung von Note-Name und Abschnitt

**Technische Details:**
- Links werden in `target_id="Note"` und `target_section="Section"` aufgeteilt
- Edge-ID enthält `variant` (Section) für Multigraph-Support
- Semantische Deduplizierung basiert auf `src->tgt:kind@sec` Key

### Atomic Section Logic (Chunking v3.9.9)

Das Chunking hält nun Sektions-Überschriften und deren Inhalte **atomar** zusammen:

**"Pack-and-Carry-Over" Verfahren:**
- Regel 1 & 2: Sektionen werden zusammengepackt, wenn sie in den Token-Limit passen
- Regel 3: Zu große Sektionen werden intelligent zerlegt, Rest wird zurück in Queue gelegt
- H1-Context Preservation: Dokumenttitel wird als Breadcrumb in alle Chunks injiziert

**Vorteile:**
- Keine getrennten Überschriften mehr
- Bessere semantische Kohärenz in Chunks
- Verbesserte Retrieval-Qualität durch vollständigen Kontext

### Registry-First Profiling (v2.13.12)

Die Konfigurationsauflösung folgt nun einer klaren Hierarchie:

1. **Frontmatter** (höchste Priorität)
2. **types.yaml Typ-Config**
3. **Global Defaults**

**Impact:**
- Note-Typen wie `value` erhalten automatisch das korrekte Profil (`structured_smart_edges_strict`)
- Keine manuellen Overrides mehr nötig für Standard-Typen
- Konsistente Metadaten in Qdrant

---

## 🔧 Verbesserungen

### Extraction & Parsing

- **Multi-line Callout-Blocks:** Korrekte Verarbeitung von mehrzeiligen `[!edge]` Callouts
- **Robuste Fallbacks:** "Headless" Blocks werden korrekt behandelt
- **Liberalisierte Regex:** Unterstützung für Umlaute und Sonderzeichen in Link-Targets

### Format-agnostische De-Duplizierung

- Kanten werden unabhängig vom Format (Inline, Callout, Wikilink) erkannt
- Verhindert Dopplungen, wenn Kanten bereits via `[!edge]` Callout vorhanden sind
- Ziel-basierte Prüfung statt String-Match

### Deterministic Hashing

- `full`-Hash inkludiert strategische Parameter (`split_level`, `strict_heading_split`)
- Konfigurationsänderungen im Frontmatter lösen zwingend Re-Import aus
- Zuverlässigere Change Detection

---

## 🐛 Bugfixes

- ✅ **Behoben:** Mehrere Links zur gleichen Note in einem Callout-Block wurden zu einer Kante gemergt
- ✅ **Behoben:** "Phantom-Knoten" durch Einbeziehung des Anchors in `target_id`
- ✅ **Behoben:** Redundante `[[rel:...]]` Links in Chunks
- ✅ **Behoben:** Inkonsistente Metadaten in Qdrant durch fehlerhafte Profil-Auflösung
- ✅ **Behoben:** `TypeError` durch Parameter-Mismatch zwischen Orchestrator und Strategien

---

## ⚠️ Breaking Changes & Migration

### Migration erforderlich

**WICHTIG:** Nach dem Update auf v2.9.1 ist ein **vollständiger Re-Import** erforderlich:

```bash
python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force
```

**Warum?**
- Behebt "Phantom-Knoten" durch korrekte Aufteilung von `[[Note#Section]]` Links
- Konsolidiert Edge-Struktur mit neuem `target_section` Feld
- Aktualisiert Chunking basierend auf Atomic Section Logic

**Was passiert beim Re-Import?**
- Alle bestehenden Links werden neu geparst und in `target_id` + `target_section` aufgeteilt
- Chunks werden mit neuer Atomic Section Logic neu generiert
- Edge-Struktur wird konsolidiert (Multigraph-Support)

**Dauer:** Abhängig von Vault-Größe (typischerweise 5-30 Minuten)

---

## 📚 API-Änderungen

### EdgeDTO erweitert

```python
class EdgeDTO(BaseModel):
    # ... bestehende Felder ...
    target_section: Optional[str] = None  # Neu: Abschnitts-Name
```

**Impact für API-Consumer:**
- Graph-Endpunkte (`/graph/{note_id}`) enthalten nun `target_section` in Edge-Objekten
- Frontend kann Section-Informationen für präzisere Visualisierung nutzen

---

## 📖 Dokumentation

Alle relevanten Dokumente wurden aktualisiert:

- ✅ `03_tech_data_model.md`: Edge Payload Schema mit `target_section`
- ✅ `02_concept_graph_logic.md`: Section-basierte Links & Multigraph-Support
- ✅ `03_tech_ingestion_pipeline.md`: Chunking-Strategien, Registry-First Profiling
- ✅ `03_tech_api_reference.md`: EdgeDTO mit `target_section`
- ✅ `01_knowledge_design.md`: Deep-Links dokumentiert
- ✅ `00_glossary.md`: Neue Begriffe ergänzt
- ✅ `04_admin_operations.md`: Migration-Hinweis

---

## 🔄 Technische Details

### Geänderte Module

**Graph Topology:**
- `app/core/graph/graph_utils.py`: `parse_link_target()` für Section-Extraktion
- `app/core/graph/graph_derive_edges.py`: `target_section` in Edge-Payload
- `app/core/graph/graph_extractors.py`: Multi-line Callout-Parser

**Chunking:**
- `app/core/chunking/chunking_strategies.py`: Atomic Section Logic (v3.9.9)
- `app/core/chunking/chunking_propagation.py`: Format-agnostische De-Duplizierung

**Ingestion:**
- `app/core/ingestion/ingestion_processor.py`: Registry-First Profiling (v2.13.12), Deterministic Hashing

**Database:**
- `app/core/database/qdrant.py`: Keyword-Index für `target_section`
- `app/core/database/qdrant_points.py`: Explizites Durchreichen von `target_section`

**API:**
- `app/models/dto.py`: `EdgeDTO` mit `target_section` Feld (v0.6.7)

### Versionsnummern

- Graph Topology: **v2.9.1**
- Chunking Strategies: **v3.9.9**
- Ingestion Processor: **v2.13.12**
- API DTO: **v0.6.7**

---

## 🚀 Upgrade-Pfad

### Für Administratoren

1. **Backup erstellen:**
   ```bash
   docker stop qdrant
   tar -czf qdrant_backup_$(date +%F).tar.gz ./qdrant_data
   docker start qdrant
   ```

2. **Code aktualisieren:**
   ```bash
   git pull origin main
   source .venv/bin/activate
   pip install -r requirements.txt
   ```

3. **Re-Import durchführen:**
   ```bash
   python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force
   ```

4. **Services neu starten:**
   ```bash
   sudo systemctl restart mindnet-prod
   sudo systemctl restart mindnet-ui-prod
   ```

### Für Entwickler

- Keine Code-Änderungen erforderlich, wenn nur API genutzt wird
- Frontend kann `target_section` Feld in Edge-Objekten nutzen (optional)

---

## 📝 Bekannte Einschränkungen

- **Migration-Dauer:** Große Vaults (>10.000 Notizen) können 30+ Minuten benötigen
- **Temporärer Speicher:** Während des Re-Imports kann Qdrant-Speicher temporär ansteigen

---

## 🙏 Danksagungen

Diese Version wurde durch umfangreiche Code-Analyse und Dokumentationsprüfung ermöglicht. Besonderer Fokus lag auf:
- Konsistenz zwischen Code und Dokumentation
- Vollständige Abdeckung aller Rollen (Entwickler, Administratoren, Anwender, Tester, Deployment)
- Klare Migration-Pfade

---

**Vollständige Changelog:** Siehe Git-Commits für detaillierte Änderungen  
**Support:** Bei Fragen zur Migration siehe [Admin Operations Guide](../04_Operations/04_admin_operations.md)