Add bounded read-only database relationship analysis profiles

docs/database-relations-v1.md

@@ -0,0 +1,108 @@
+# DB-Beziehungsanalyse v1
+
+Die Operation `project.query` akzeptiert bei konfigurierten Analyseprofilen:
+
+```json
+{"kind":"database.relations","profile":"creature_spawn_context","value":23487}
+```
+
+Die LLM bestimmt nur Profil und Startwert. Tabellen, Spalten, Gleichheitsbeziehungen
+und Projektionen kommen aus der vertrauenswürdigen Projektkonfiguration. Es gibt
+keine freie SQL-Eingabe, keine automatische Fremdschlüsselvermutung und keine
+eingebaute Diagnose. Grundwerkzeuge bleiben für weitere Fragen verfügbar.
+
+## Konfiguration und Systemgrenze
+
+`relations_file = "project-relations.vcore.toml"` steht auf der obersten Ebene
+der Projekt-TOML. Alternativ können Profile direkt unter `[relations]` definiert
+werden; beide Varianten zugleich sind unzulässig. Das Vcore-Beispiel ist getrennte
+Adapterkonfiguration. Der Kern kennt keine Kreaturen, Quests oder Gebietsnummern.
+
+Ein Profil hat eine Beschreibung und eine geordnete Liste benannter Knoten:
+
+- Der erste Knoten filtert `table.match_column` auf den Startwert.
+- Folgeknoten filtern ihre `match_column` auf die eindeutigen, nichtleeren Werte
+  von `parent_column` in den zurückgegebenen Zeilen eines früheren Knotens.
+- `columns` bestimmt die zurückzugebenden Spalten. `group_by` kann eine Verteilung
+  über höchstens fünf dieser Spalten ergänzen.
+
+Verzweigungen sind möglich, Zyklen nicht. Unterstützt sind direkte
+Gleichheitsbeziehungen; zusammengesetzte Schlüssel, rekursive Traversierung und
+Transformationen wie der Betrag negativer Event-IDs werden nicht automatisch
+interpretiert. Zusätzliche Profile können unabhängig von der Kernlogik ergänzt
+werden. Eine ausbleibende Zuordnung ist noch keine Feststellung eines DB-Fehlers.
+
+Das Vcore-Profil untersucht `creature_template` → `creature` →
+`game_event_creature` → `game_event`. Es prüft weder dynamische Spawnpfade im
+Sourcecode noch den aktuellen Zustand eines laufenden Servers. Koordinaten werden
+in diesem Profil nicht übertragen; sie sind bei Bedarf mit Grundwerkzeugen lesbar.
+
+## Grenzen, Vollständigkeit und Provenienz
+
+Pro Profil sind höchstens zwölf Knoten und dreißig projizierte Spalten je Knoten
+erlaubt. `ProjectLimits.max_rows` begrenzt jede Ergebnismenge, `timeout_seconds`
+die gesamte Analyse und einzelne SQL-Statements, `max_result_bytes` das Ergebnis.
+Dies sind Sicherheitsvorgaben, keine Grenzen des Case-Paketformats. Ein Profilaufruf
+ist eine budgetierte `project.query`-Aktion mit begrenzter interner Arbeit, keine
+Folge zusätzlicher LLM-Aufrufe. Die vorhandene Aktionskostenkonfiguration bleibt
+maßgeblich; dieses Werkzeug ändert keine Budgetwerte.
+
+Alle Abfragen eines Aufrufs erfolgen in einer gemeinsamen Read-only-Transaktion
+mit Repeatable Read und konsistentem Snapshot. Nur InnoDB/XtraDB-Tabellen sind
+dafür zugelassen; andere Engines erzeugen kontrolliert
+`PROJECT_RELATIONS_SNAPSHOT_UNSUPPORTED`. Die Transaktion wird zurückgerollt und
+geschlossen. Angefragte Identifikatoren und Spalten werden geprüft, Werte gebunden.
+Ganzzahlige Startspalten verlangen einen echten Integer, damit MySQL keine
+beliebigen Texte implizit zu IDs konvertiert.
+
+Jeder Knoten liefert genaue Filter, projizierte Zeilen, benötigte Spaltenmetadaten,
+Anzahl der zurückgegebenen Zeilen und getrennte Angaben zu lokaler Begrenzung und
+vollständiger Elternmenge. Verteilungen beziehen sich ausdrücklich nur auf die
+zurückgegebenen Zeilen. Eine begrenzte Elternmenge macht alle abhängigen Ergebnisse
+unvollständig, auch wenn deren eigene Seite nicht begrenzt wurde. Die tatsächliche
+Gesamtzahl außerhalb einer begrenzten Seite wird nicht behauptet.
+
+Ohne Elternschlüssel wird eine Folgeabfrage übersprungen und als solche markiert.
+Ein fehlender Startdatensatz schließt insbesondere verwaiste Zeilen in anderen
+Tabellen nicht aus. `complete_configured_relations` bedeutet ausschließlich:
+Die konkret konfigurierten Verbindungen wurden ohne Seitenbegrenzung verarbeitet.
+Es bedeutet weder vollständige Datenbankanalyse noch Ausschluss anderer Ursachen.
+Für größere Mengen stehen die bisherigen paginierbaren Grundwerkzeuge bereit.
+
+Der Capture enthält Snapshot-Bindung, vollständigen Profilplan und dessen Hash.
+Er wird wie bisher unveränderlich als Evidenz gespeichert und ist ohne erneute
+DB-Abfrage transportierbar. Änderungen am Profil ändern die Capture-Bindung;
+Änderungen gegenüber einem bereits begonnenen Untersuchungskontext werden
+abgelehnt. Abfragen werden während des Controller-Zyklus eingefroren. Die konkrete
+DB-Momentaufnahme hängt weiterhin von der ehrlich konfigurierten Snapshot-ID ab.
+
+## LLM-Anbindung und Kompatibilität
+
+Neue Kontexte mit Profilen erhalten Katalog, Argumentvertrag und die Empfehlung,
+passende größere Werkzeuge zuerst zu verwenden. Sie müssen diese nicht verwenden.
+Der bestehende Cache kann den Werkzeugkatalog wie andere stabile Kontextbestandteile
+wiederverwenden. Eine zusätzliche Zusammenfassungs-LLM gibt es nicht.
+
+Ohne Profile bleibt die bisherige Promptstruktur bestehen. Gespeicherte Kontexte
+behalten ihren damaligen Vertrag. Die portablen Request-, State- und Capture-Schemas
+akzeptieren die zusätzliche Operation. Die Prüfung numerischer Codingangaben
+berücksichtigt auch die hier gewonnenen Zeilen.
+
+## Lokale Prüfung
+
+Tests decken parametrisierte Abfragen, Allowlist, Konfigurationsfehler, begrenzte
+Elternmengen, leere Ergebnisse, Zeit-/Bytegrenzen, Snapshot-Engine-Prüfung,
+Paketvalidierung, Budgetierung und Wiederaufnahme ab. Ein simulierter LLM-Durchlauf
+prüft die Werkzeugauswahl in der hybriden Schleife.
+
+Der opt-in Test an der lokalen Vcore-Testdatenbank prüft für Entry 23487 eine
+Vorlage, achtzehn Spawns ausschließlich auf Map 1, achtzehn dazugehörige
+Event-Verknüpfungen und Event 24. Der projizierte Capture umfasst beim geprüften
+Backup ungefähr 8,3 KB. Das ist ein Funktionsnachweis, keine Kostenprognose und
+noch kein Nachweis der Werkzeugwahl durch eine echte LLM. Es wurden dafür keine
+kostenpflichtigen API-Aufrufe ausgeführt.
+
+```powershell
+$env:VBA_TEST_PROJECT_CONFIG = "config/project.local.toml"
+.\.venv\Scripts\python.exe -m pytest tests/test_database_relations.py -q
+```