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:

templates:
  - name: "simple_chain"
    slots: ["start", "end"]

Rich Format (preferred):

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:

templates:
  - name: "my_template"
    slots: ["slot1", "slot2"]

Rich Template:

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