VianoBugAnalysis/docs/database-relations-v1.md

DB-Beziehungsanalyse v1

Die Operation project.query akzeptiert bei konfigurierten Analyseprofilen:

{"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.

$env:VBA_TEST_PROJECT_CONFIG = "config/project.local.toml"
.\.venv\Scripts\python.exe -m pytest tests/test_database_relations.py -q