# Note-Scope Extraktions-Zonen (v4.5.8)

**Version:** v4.5.8  
**Status:** Aktiv  
**Aktualisiert:** WP-24c Phase 3 Agentic Edge Validation

## Übersicht

Das Mindnet-System unterstützt nun **Note-Scope Extraktions-Zonen**, die es ermöglichen, Links zu definieren, die der gesamten Note zugeordnet werden (nicht nur einem spezifischen Chunk).

### Unterschied: Chunk-Scope vs. Note-Scope

- **Chunk-Scope Links** (`scope: "chunk"`): 
  - Werden aus dem Text-Inhalt extrahiert
  - Sind lokalem Kontext zugeordnet
  - `source_id` = `chunk_id`
  
- **Note-Scope Links** (`scope: "note"`):
  - Werden aus speziellen Markdown-Sektionen extrahiert
  - Sind der gesamten Note zugeordnet
  - `source_id` = `note_id`
  - Haben höchste Priorität bei Duplikaten

## Verwendung

### Format

Erstellen Sie eine Sektion mit einem der folgenden Header:

- `## Smart Edges`
- `## Relationen`
- `## Global Links`
- `## Note-Level Relations`
- `## Globale Verbindungen`

**Wichtig:** Die Header müssen exakt (case-insensitive) übereinstimmen.

### Beispiel

```markdown
---
type: decision
title: Technologie-Entscheidung
---

# Entscheidung über Technologie-Stack

Wir haben uns für React entschieden...

## Begründung

React bietet bessere Performance...

## Smart Edges

[[rel:depends_on|Performance-Analyse]]
[[rel:uses|TypeScript]]
[[React-Dokumentation]]

## Weitere Überlegungen

Hier ist weiterer Inhalt...
```

### Unterstützte Link-Formate

In Note-Scope Zonen werden folgende Formate unterstützt:

1. **Typed Relations:**
   ```markdown
   ## Smart Edges
   [[rel:depends_on|Ziel-Notiz]]
   [[rel:uses|Andere Notiz]]
   ```

2. **Standard Wikilinks:**
   ```markdown
   ## Smart Edges
   [[Ziel-Notiz]]
   [[Andere Notiz]]
   ```
   (Werden als `related_to` interpretiert)

3. **Callouts:**
   ```markdown
   ## Smart Edges
   > [!edge] depends_on:[[Ziel-Notiz]]
   > [!edge] uses:[[Andere Notiz]]
   ```

## Technische Details

### ID-Generierung

Note-Scope Links verwenden die **exakt gleiche ID-Generierung** wie Symmetrie-Kanten in Phase 2:

```python
_mk_edge_id(kind, note_id, target_id, "note", target_section=sec)
```

Dies stellt sicher, dass:
- ✅ Authority-Check in Phase 2 korrekt funktioniert
- ✅ Keine Duplikate entstehen
- ✅ Symmetrie-Schutz greift

### Provenance

Note-Scope Links erhalten:
- `provenance: "explicit:note_zone"`
- `confidence: 1.0` (höchste Priorität)
- `scope: "note"`
- `source_id: note_id` (nicht `chunk_id`)

### Priorisierung

Bei Duplikaten (gleiche ID):
1. **Note-Scope Links** haben **höchste Priorität**
2. Dann Confidence-Wert
3. Dann Provenance-Priority

**Beispiel:**
- Chunk-Link: `related_to:Note-A` (aus Text)
- Note-Scope Link: `related_to:Note-A` (aus Zone)
- **Ergebnis:** Note-Scope Link wird beibehalten

## Best Practices

### ✅ Empfohlen

1. **Note-Scope für globale Verbindungen:**
   ```markdown
   ## Smart Edges
   [[rel:depends_on|Projekt-Übersicht]]
   [[rel:part_of|Größeres System]]
   ```

2. **Chunk-Scope für lokale Referenzen:**
   ```markdown
   In diesem Abschnitt verweisen wir auf [[rel:uses|Spezifische Technologie]].
   ```

3. **Kombination:**
   ```markdown
   # Hauptinhalt
   
   Lokale Referenz: [[rel:uses|Lokale Notiz]]
   
   ## Smart Edges
   
   Globale Verbindung: [[rel:depends_on|Globale Notiz]]
   ```

### ❌ Vermeiden

1. **Nicht für lokale Kontext-Links:**
   - Nutzen Sie Chunk-Scope Links für lokale Referenzen
   - Note-Scope ist für Note-weite Verbindungen gedacht

2. **Nicht zu viele Note-Scope Links:**
   - Beschränken Sie sich auf wirklich Note-weite Verbindungen
   - Zu viele Note-Scope Links können die Graph-Struktur verwässern

## Integration mit Phase 3 Validierung (WP-24c v4.5.8)

Note-Scope Links können **zwei verschiedene Provenance** haben:

### Explizite Note-Scope Links (Keine Validierung)

Links in `## Smart Edges` Zonen werden als `explicit:note_zone` markiert und **direkt übernommen** (keine Phase 3 Validierung):

```markdown
## Smart Edges

[[rel:depends_on|System-Architektur]]
[[rel:part_of|Gesamt-System]]
```

**Vorteil:** Sofortige Übernahme, höchste Priorität, keine Validierungs-Kosten.

### Validierte Note-Scope Links (Phase 3 Validierung)

Links in `### Unzugeordnete Kanten` erhalten `candidate:` Präfix und werden in **Phase 3** validiert:

```markdown
### Unzugeordnete Kanten

related_to:Mögliche Verbindung
depends_on:Unsicherer Link
```

**Validierungsprozess:**
1. Links erhalten `candidate:` Präfix
2. **Phase 3 Validierung:** LLM prüft semantisch gegen Note-Summary oder Note-Text (Note-Scope Kontext-Optimierung)
3. **Erfolg (VERIFIED):** `candidate:` Präfix wird entfernt, Kante wird persistiert
4. **Ablehnung (REJECTED):** Kante wird **nicht** in die Datenbank geschrieben

**Wichtig:** 
- Links in `### Unzugeordnete Kanten` werden als `candidate:` markiert und durchlaufen Phase 3
- Links in `## Smart Edges` werden als `explicit:note_zone` markiert und **nicht** validiert (direkt übernommen)
- **Note-Scope Kontext-Optimierung:** Bei Note-Scope Kanten nutzt Phase 3 `note_summary` (Top 5 Chunks) oder `note_text` (aggregierter Gesamttext) für bessere Validierungs-Genauigkeit

## Beispiel: Vollständige Notiz

```markdown
---
type: decision
title: Architektur-Entscheidung
---

# Architektur-Entscheidung

Wir haben uns für Microservices entschieden...

## Begründung

### Performance

Microservices bieten bessere Skalierbarkeit. Siehe auch [[rel:uses|Kubernetes]] für Orchestrierung.

### Sicherheit

Wir nutzen [[rel:enforced_by|OAuth2]] für Authentifizierung.

## Smart Edges

[[rel:depends_on|System-Architektur]]
[[rel:part_of|Gesamt-System]]
[[rel:uses|Cloud-Infrastruktur]]

## Weitere Details

Hier ist weiterer Inhalt...
```

**Ergebnis:**
- `uses:Kubernetes` → Chunk-Scope (aus Text)
- `enforced_by:OAuth2` → Chunk-Scope (aus Text)
- `depends_on:System-Architektur` → Note-Scope (aus Zone)
- `part_of:Gesamt-System` → Note-Scope (aus Zone)
- `uses:Cloud-Infrastruktur` → Note-Scope (aus Zone)

## Code-Referenzen

- **Extraktion:** `app/core/graph/graph_derive_edges.py` → `extract_note_scope_zones()`
- **Integration:** `app/core/graph/graph_derive_edges.py` → `build_edges_for_note()`
- **Header-Liste:** `NOTE_SCOPE_ZONE_HEADERS` in `graph_derive_edges.py`

## FAQ

**Q: Können Note-Scope Links auch Section-Links sein?**  
A: Ja, `[[rel:kind|Target#Section]]` wird unterstützt. `target_section` fließt in die ID ein.

**Q: Was passiert, wenn ein Link sowohl in Chunk als auch in Note-Scope Zone steht?**  
A: Der Note-Scope Link hat Vorrang und wird beibehalten.

**Q: Werden Note-Scope Links validiert?**  
A: Das hängt von der Zone ab:
- **`## Smart Edges`:** Nein, werden direkt übernommen (explizite Links, keine Validierung)
- **`### Unzugeordnete Kanten`:** Ja, durchlaufen Phase 3 Validierung (candidate: Präfix)

**Q: Was ist der Unterschied zwischen Note-Scope in Smart Edges vs. Unzugeordnete Kanten?**  
A: 
- **Smart Edges:** Explizite Links, sofortige Übernahme, höchste Priorität
- **Unzugeordnete Kanten:** Validierte Links, Phase 3 Prüfung, candidate: Präfix

**Q: Kann ich eigene Header-Namen verwenden?**  
A: Aktuell nur die vordefinierten Header. Erweiterung möglich durch Anpassung von `NOTE_SCOPE_ZONE_HEADERS`.

## Zusammenfassung

- ✅ **Note-Scope Zonen:** `## Smart Edges` oder ähnliche Header
- ✅ **Format:** `[[rel:kind|target]]` oder `[[target]]`
- ✅ **Scope:** `scope: "note"`, `source_id: note_id`
- ✅ **Priorität:** Höchste Priorität bei Duplikaten
- ✅ **ID-Konsistenz:** Exakt wie Symmetrie-Kanten (Phase 2)