mindnet_obsidian/docs/CHAIN_INSPECTOR_V04_REPORT.md

# Chain Inspector v0.4 - Chain Template Matching Implementierungsbericht

**Status:** ✅ Vollständig implementiert und getestet  
**Datum:** 2025-01-XX  
**Version:** v0.4.0  
**Basiert auf:** Chain Inspector v0.2.0

---

## Übersicht

Chain Inspector v0.4 erweitert v0.2 um **Chain Template Matching** - eine deterministische Template-Matching-Funktion, die Templates aus `chain_templates.yaml` gegen den lokalen Subgraph um die aktuelle Section matched und slot-basierte Findings produziert.

## Neue Features

### 1. Template Matching Algorithmus

**Funktionsweise:**
1. Baut Candidate-Node-Set aus aktueller Section und Nachbarn (max 30 Nodes)
2. Für jedes Template:
   - Normalisiert Template zu rich format (unterstützt auch minimal v0)
   - Filtert Candidate-Nodes pro Slot nach `allowed_node_types`
   - Findet beste Assignment via Backtracking
   - Scored Assignment: +10 pro erfüllter Link, +2 pro gefülltem Slot, -5 pro fehlendem required Link
3. Gibt Top-K Matches zurück (K=1 für v0)

**Node-Type-Erkennung:**
- Extrahiert `type` aus Frontmatter
- Falls nicht vorhanden → `"unknown"`
- Section-Nodes verwenden Note-Type der besitzenden Datei

**Edge-Role-Erkennung:**
- Verwendet canonical edge types (via `edge_vocabulary.md`)
- Mappt zu Rollen via `chain_roles.yaml`
- Unterstützt sowohl canonical als auch raw types (permissiv)

### 2. Template-Format-Unterstützung

**Minimal v0:**
```yaml
templates:
  - name: "simple_chain"
    slots: ["start", "end"]
```

**Rich Format (preferred):**
```yaml
defaults:
  matching:
    required_links: false

templates:
  - name: "trigger_transformation_outcome"
    description: "Causal chain template"
    slots:
      - id: "trigger"
        allowed_node_types: ["experience"]
      - id: "transformation"
        allowed_node_types: ["insight"]
      - id: "outcome"
        allowed_node_types: ["decision"]
    links:
      - from: "trigger"
        to: "transformation"
        allowed_edge_roles: ["causal"]
      - from: "transformation"
        to: "outcome"
        allowed_edge_roles: ["causal"]
    matching:
      required_links: true
```

**Permissive Config:**
- Unbekannte Felder werden ignoriert
- `defaults.matching.required_links` als Fallback
- `template.matching.required_links` überschreibt Defaults

### 3. Template-basierte Findings

**`missing_slot_<slotId>` (Severity: WARN)**
- Trigger: Best match score >= 0 ODER slotsFilled >= 2 UND mindestens ein Slot fehlt
- Message: `"Template <name>: missing slot <slotId> near current section"`
- Evidence: current context + templateName + missingSlots

**`weak_chain_roles` (Severity: INFO)**
- Trigger: Template-Links erfüllt, aber nur durch non-causal Rollen
- Message: `"Template <name>: links satisfied but only by non-causal roles"`
- Causal-Rollen: `["causal", "influences", "enables_constraints"]`

**`slot_type_mismatch` (Severity: WARN)**
- Optional für v0 (nicht implementiert, da Matching Mismatches verhindert)

### 4. Templates Source Provenance

**Report-Feld:** `templatesSource`
- `path`: Resolved path zu `chain_templates.yaml`
- `status`: `"loaded"` | `"error"` | `"using-last-known-good"`
- `loadedAt`: Timestamp
- `templateCount`: Anzahl Templates

## Technische Implementierung

### Geänderte Dateien

#### `src/dictionary/types.ts`
- **Erweiterte Interfaces:**
  - `ChainTemplateSlot`: `{ id, allowed_node_types? }`
  - `ChainTemplateLink`: `{ from, to, allowed_edge_roles? }`
  - `ChainTemplate`: Unterstützt sowohl `slots: string[]` als auch `slots: ChainTemplateSlot[]`
  - `ChainTemplatesConfig`: `defaults?` hinzugefügt

#### `src/dictionary/parseChainTemplates.ts`
- **Erweitert:** Parsing für `defaults`, `links`, `matching`, `description`
- **Permissive:** Ignoriert unbekannte Felder

#### `src/analysis/templateMatching.ts` (NEU)
- **Hauptfunktion:** `matchTemplates()`
- **Helper-Funktionen:**
  - `extractNoteType()`: Extrahiert `type` aus Frontmatter
  - `normalizeTemplate()`: Konvertiert minimal zu rich format
  - `buildCandidateNodes()`: Baut Candidate-Node-Set (max 30)
  - `nodeMatchesSlot()`: Prüft Slot-Constraints
  - `getEdgeRole()`: Mappt Edge-Type zu Role
  - `findEdgeBetween()`: Findet Edge zwischen zwei Nodes
  - `scoreAssignment()`: Scored Assignment
  - `findBestAssignment()`: Backtracking-Algorithmus

#### `src/analysis/chainInspector.ts`
- **Erweitertes Interface:** `ChainInspectorReport`
  - `templateMatches?: TemplateMatch[]`
  - `templatesSource?: { path, status, loadedAt, templateCount }`
- **Erweiterte Funktion:** `inspectChains()`
  - Parameter: `chainTemplates?`, `templatesLoadResult?`
  - Ruft `matchTemplates()` auf
  - Generiert Template-basierte Findings
- **Exportiert:** `resolveCanonicalEdgeType()` für Template-Matching

#### `src/commands/inspectChainsCommand.ts`
- **Erweiterte Funktion:** `executeInspectChains()`
  - Parameter: `chainTemplates?`, `templatesLoadResult?`
  - Übergibt Templates an `inspectChains()`
- **Erweiterte Funktion:** `formatReport()`
  - Zeigt "Template Matches" Sektion
  - Zeigt "Templates Source" Info

#### `src/main.ts`
- **Update:** Command lädt Chain Templates und übergibt sie

#### `src/tests/analysis/templateMatching.test.ts` (NEU)
- **3 Tests:**
  1. `should match template with rich format and all slots filled`
  2. `should detect missing slot when edge is missing`
  3. `should produce deterministic results regardless of edge order`

### Template-Matching-Algorithmus

**Backtracking:**
- Iteriert Slots in stabiler Reihenfolge
- Pro Slot: Testet alle passenden Candidate-Nodes
- Verhindert Duplikate (kein Node für mehrere Slots)
- Erlaubt ungefüllte Slots
- Evaluated alle möglichen Assignments

**Scoring:**
- `+10`: Pro erfüllter Link-Constraint (Edge existiert mit erlaubter Role)
- `+2`: Pro gefülltem Slot
- `-5`: Pro fehlendem required Link (wenn `required_links: true`)

**Determinismus:**
- Sortierung: Score desc, dann Name asc
- Top-K: K=1 für v0
- Node-Keys: Deterministisch sortiert (alphabetisch)

## Verwendung

### In Obsidian

1. Öffnen Sie eine Markdown-Datei mit Edges
2. Positionieren Sie den Cursor in einer Section
3. Öffnen Sie die Command Palette (Strg+P / Cmd+P)
4. Wählen Sie: **"Mindnet: Inspect Chains (Current Section)"**
5. Prüfen Sie die Console (Strg+Shift+I / Cmd+Option+I) für den Report

**Erwartete Ausgabe:**
- `templateMatches` Sektion zeigt Top-Matches
- `templatesSource` zeigt Provenance-Info
- `missing_slot_*` Findings für fehlende Slots
- `weak_chain_roles` Finding für non-causal Links

### Template-Konfiguration

**Erforderliche Datei:** `chain_templates.yaml` (Standard: `"_system/dictionary/chain_templates.yaml"`)

**Minimales Template:**
```yaml
templates:
  - name: "my_template"
    slots: ["slot1", "slot2"]
```

**Rich Template:**
```yaml
defaults:
  matching:
    required_links: false

templates:
  - name: "causal_chain"
    description: "Three-step causal chain"
    slots:
      - id: "cause"
        allowed_node_types: ["experience", "event"]
      - id: "effect"
        allowed_node_types: ["insight", "decision"]
    links:
      - from: "cause"
        to: "effect"
        allowed_edge_roles: ["causal", "influences"]
```

## Test-Ergebnisse

### Erfolgreiche Tests (3/3)

✅ **Rich Template Matching:**
- Test: Template mit 3 Slots, alle gefüllt
- Ergebnis: Alle Slots zugewiesen, keine `missing_slot` Findings

✅ **Missing Slot Detection:**
- Test: Template mit 3 Slots, aber fehlender Edge
- Ergebnis: `missing_slot_outcome` Finding korrekt erkannt

✅ **Determinismus:**
- Test: Identische Edges in unterschiedlicher Reihenfolge
- Ergebnis: Identische Matches, deterministische Sortierung

### Build-Status
✅ **TypeScript kompiliert ohne Fehler**  
✅ **Keine Linter-Fehler**  
✅ **Alle Tests bestehen**

## Bekannte Einschränkungen

1. **Top-K Limit:** Nur Top-1 Match pro Template (K=1 für v0)
2. **Node-Limit:** Max 30 Candidate-Nodes (brute-force safety)
3. **Slot-Limit:** Backtracking für <=5 Slots empfohlen (größere Templates können langsam sein)
4. **Type-Mismatch:** `slot_type_mismatch` Finding nicht implementiert (Matching verhindert Mismatches)

## Vergleich v0.2 vs v0.4

| Feature | v0.2 | v0.4 |
|---------|------|------|
| Chain Inspector Analysis | ✅ | ✅ |
| Alias-aware Role Classification | ✅ | ✅ |
| Dangling Target Detection | ✅ | ✅ |
| Analysis Meta | ✅ | ✅ |
| Template Matching | ❌ | ✅ |
| Slot-based Findings | ❌ | ✅ |
| Templates Source Provenance | ❌ | ✅ |
| Rich Template Format Support | ❌ | ✅ |

## Zusammenfassung

Chain Inspector v0.4 erweitert v0.2 erfolgreich um:

✅ **Template Matching** - Deterministisches Matching von Templates gegen lokalen Subgraph  
✅ **Slot-based Findings** - `missing_slot_*` und `weak_chain_roles` Findings  
✅ **Rich Template Format** - Unterstützung für `allowed_node_types`, `allowed_edge_roles`, `defaults`  
✅ **Templates Source Provenance** - Verifizierbare Template-Herkunft im Report  
✅ **Permissive Config** - Ignoriert unbekannte Felder sicher  
✅ **Deterministic Output** - Stabile Sortierung für Golden Tests  

**Alle Tests bestehen** (3/3)  
**TypeScript kompiliert ohne Fehler**  
**Keine Linter-Fehler**  
**Production Ready** ✅

Die Implementierung bildet eine solide Grundlage für weitere Chain Intelligence Features in Phase 2.

---

**Erstellt:** 2025-01-XX  
**Autor:** Cursor AI Agent  
**Status:** ✅ Production Ready