# Engine–Modern-UI: JSON-Datenvertrag für Desktop, Live und Nachspiel **Arbeitsentwurf der Nacht 26./27. Oktober 2026, keine Fertigmeldung.** Dieses Paket benennt, was die Oberfläche benötigt, welche Quellen bereits belegt sind und welche Adapter beziehungsweise Engineentscheidungen noch fehlen. Es implementiert weder Saisonregeln noch einen Engineadapter oder eine neue Matchoberfläche. Alle Beispiele sind synthetisch. Sie dürfen nicht als gespielte Engineergebnisse, als HTML-Referenzwerte oder als Regression gegen Originaldaten ausgegeben werden. | Einstieg | Inhalt | | --- | --- | | [Kurzübergabe für Claude](MVP_FOR_CLAUDE.md) | Schlanker Einstieg und Lieferreihenfolge für die erste echte Anbindung | | [Schemas](schemas/ui-contract.schema.json) | JSON Schema 2020-12; gemeinsame Typen, Readmodels, Kommandos, Fehler und Ergebnisse | | [Index](schemas/contract-index.json) | Namen der vorgeschlagenen Reads und Commands | | [Menüvertrag](menu-contracts.json) | 47 Menü-/Auswertungsbereiche mit sichtbaren Daten und Code-/HTML-Quellen | | [Almanach und Auswertungen](ALMANAC.md) | Ereignisse, Identitäten, Vollständigkeit, Korrekturen, Aggregationen und notwendige Zusatzledger | | [Pressevertrag](PRESS.md) | Semantische Events, unveränderliche DE/EN-Snapshots und Lösch-Dedupe | | [Offene Entscheidungen](OPEN_DECISIONS.md) | Priorisierte Rückfragen für Claude/Engine, ohne stillschweigende Antworten | | [Beispiele](examples/index.json) | 53 Dateien: vier Manager, Verein/National, ET, PSO, Indoor, unbekannte Altphasen, Geschäftsdaten und Aufgeben | | [Quellbasis](provenance.json) | Getrennte Revisionen und Hashes der geprüften Vertragsquellen | | [QA](QA.md) | Tatsächlich ausgeführte Schema-/Semantikprüfungen und Grenzen | ## Zwei öffentliche Grundlagen und eine private Referenz Die untersuchte Modern-UI-/Enginebasis ist `origin/0.3` bei `a207b0129e06f0659a5e7b30afa3680739a33029`. Das im selben Repository geprüfte `origin/main` zeigt auf `b879d5be008739f69afef562fb4bce56f1bdc778` und enthält **keine** `src/modern`- oder `docs/new_engine`-Dateien. Daraus folgt keine Aussage über einen möglicherweise getrennten, neueren Claude-Enginezweig; dessen Repository und Revision sind noch abzugleichen. Änderungen an diesen Grundlagen müssen vor der Implementierung erneut verglichen werden. Die private HTML-Referenz hat den separat protokollierten Git-Stand zunächst `f8932de2009137e738962763c5fcbb75c2467570`; der abschließende Hashabgleich protokolliert `72ddff945f75276d1b0a93e7a9cb5a61beefa9dd` plus die parallel entstandenen Working-Tree-Änderungen. `match-model.js`, `match-broadcast.js`, `match-intervention.js`, `post-match.js` und die Desktop- Menüprovider wurden für Daten und Interaktionen gelesen. Zusätzliche uncommittete Änderungen sind unter `workingTreeChanges` und mit ihren tatsächlichen Dateihashes protokolliert. Die JS-Dateihashes sind ein Inventar, keine Behauptung einer vollständigen Browser- oder Bild-QA. Öffentlich werden weder Originalgrafiken noch Originaltextinventare oder echte Namen/Spieldaten mitgeliefert. Neue Manager-Aufgeben-Anforderungen stammen aus dem Nutzerauftrag; ihre Auflistung behauptet noch keinen HTML-/Enginecode. ## Was heute vorhanden ist `ModernSession::read()` und `read_statistics()` liefern bereits JSON für `status`, `leagues`, `table`, `fixtures`, `squad`, `toto`, `sponsor`, `competitions`, `winners` und `player_stats`. Diese Antworten sind **nicht** bereits das hier vorgeschlagene `bmh-modern-ui@draft1`-Protokoll: durchgängiger Umschlag, Manager-/Sessionidentitäten, Scope, Pagination und Revision fehlen teilweise. Zudem benutzt die Leseseite bisher den aktiven Manager der Engine. Daneben existieren zahlreiche C++-Projektionen und revisionierte Dienste für Desktop, Transfers, Bank, Verträge, Trainingslager und Liveeingriffe. Ihre Existenz ist in `menu-contracts.json` belegt. Ein C++-Request mit Laufzeitindizes, Callbacks oder Quelladressfeldern ist noch kein stabiler JSON-DTO-Vertrag. Der Adapter muss solche internen Bezüge in IDs und semantische Aktionen übersetzen. Keine UI greift direkt auf `GameState`, Archive oder RNG zu. Die aktuelle native Modern UI verwendet für viele Menüs weiterhin `DemoSource` und deterministische Vorschauen. Der während der Nacht ergänzte `live-ticker-adapter.js` ist eine getrennte HTML-Demoadaption; seine aus Portraits gebildeten Manager-IDs und Zeit/ID- Sortierung sind kein Enginevertrag. Die initial gelesene HTML-Übertragung war eine 90-Minuten-Club-Demo. Die Nacht-Fassung normalisiert jetzt `context.role/surface/managerPortrait` und zeigt Club-Outdoor mit 90, Club-Indoor mit 40 Minuten sowie National-Outdoor. Diese 40 Minuten und die Skalierung synthetischer Ereignisse sind **Dummyregeln**, keine bestätigte Enginezeit. Timer, Torschützenformeln und Elf-des-Tages-Wertung sind keine Enginevorgabe. Der spätere Adapter darf weder diese Regeln übernehmen noch fehlende echte Werte durch die Demo ersetzen. ## Verbindliche Entwurfsprinzipien - Daten sind JSON-Objekte, Zahlen mit Einheiten und logische Assetreferenzen. Keine HTML-, RML-, CSS- oder SVG-Fragmente aus der Engine. `Text.text` ist **Plaintext**; die UI behandelt ihn als Text, nie als Markup. - `worldId/worldRevision` bezeichnet den geladenen Datensatz. `careerId` trennt Karrieren derselben Welt. `stateRevision` bezeichnet den aktiven Zustand; `projectionRevision` zusätzlich Korrektur-/Aggregationsstände. Vor Karriere- start dürfen Welt/Karriere unbekannt sein und bleiben `null`. - IDs sind stabile Zeichenketten. Manageridentität bleibt über Vereinswechsel, Umbenennung und Aufgeben bestehen. Runtime-Slots, Rang, Tabellenposition, Bildindex und Anzeigename sind niemals fachliche Identität. - Alle Reads sind frei von **Spiel-RNG**, Buchung, Fortschritt und Spielrevision. Auswahl, Scrollen, Picker-Abbruch, Theme, Chartschalter und Ticker-Abspieltempo bleiben UI-Zustand. Eine existierende C++-„Preview“, die Quoten erzeugt und RNG/Zustand fortschreibt, wird ausdrücklich über `quote.request` adaptiert, nicht während eines vermeintlich harmlosen Reads aufgerufen. - Mutationen tragen `requestId`, Welt-/Karriere-ID, `expectedRevision`, Manager-/Team-/Scopeidentität und bei Bedarf Quote-/Live-/Fortsetzungstoken. Ownerangaben im JSON sind **keine Autorisierung**: die Session prüft sie gegen ihren tatsächlichen aktiven Kontext. Erfolg wird genau einmal publiziert; Eine **protokoll-/validierungsbedingte** Ablehnung erhält Zustand, beide RNGs, Geld und Revision. Ein fachlich erfolgloser, aber regelgerecht ausgeführter Versuch (z. B. Angebot abgelehnt/Abwerben versucht) kann dagegen ein akzeptierter Command mit `outcome=offer_rejected` und neuem Zustand sein. Solche Enginefolgen werden nicht fälschlich als rollbackpflichtiger Transportfehler ausgegeben. - Derselbe `requestId` darf nach Timeout nicht doppelt buchen. Gleiches Payload erhält das gespeicherte Ergebnis oder einen eindeutigen Duplikatstatus; verändertes Payload bei gleicher ID wird abgewiesen. Aufbewahrungsdauer und Verhalten über Neustarts stehen unter D03 zur Entscheidung. - `Availability` und `Coverage` trennen fehlend, unvollständig und belegt. `0` ist ein bekannter Nullwert; unbekannt ist `null` plus Grund. Fehlende Kader erzeugen keine Phantomspieler. Kein fremder Verein wird als Ersatzmanagerteam gewählt. `unavailable` darf der Renderer neutral darstellen. ## Einheiten, Geld und Zeit `Money={minor, currency, minorUnits}` verwendet eine vorzeichenbehaftete **Dezimalzeichenkette** für die kleinste Währungseinheit. `"1500"`, EUR, 2 bedeutet 15 Euro. Das vermeidet Präzisionsverlust in JS oberhalb von 2^53. Dasselbe gilt für uint64-Revisionen und Sequenzen. Werte müssen zusätzlich in den vereinbarten int64-/uint64-Grenzen liegen. Dies ist eine Entwurfsentscheidung, keine Behauptung einer schon umgestellten Engine; Alternative siehe D01. Die drei Schichten dürfen nicht durch gleichnamige `cash`-Felder vermischt werden: | Schicht | Beispiel 15 Euro | Richtige Grenze | | --- | --- | --- | | Vorhandene Engine-Reads / bisheriges HTML-Dummy `bank.cash` | `15` ganze Euro | Einmal geprüft nach Minor Units normalisieren. | | Neuer JSON-DTO | `{minor:"1500",currency:"EUR",minorUnits:2}` | Exakte kanonische Transportform, keine formatierte Zeichenkette. | | Bisheriger HTML-Formatter `submenus.money(n)` | `money(15)` | Erwartet ganze/anzeigefertige Euro, also DTO vorher **gezielt zurück** übersetzen; nicht `money(1500)`. | | Nativer Demo-/neuer Money-Formatter | Minor-Unit-Wert `1500` | Bereits Minor Units: nicht noch einmal ×100 skalieren. | Der HTML-Adapter darf daher **kein blindes ×100** übernehmen. Bestehende HTML- Statewerte und native Demostände brauchen getrennte, versionierte Adapter. Größere Decimalstrings dürfen für Anzeige nicht ungeprüft in einen ungenauen JS-Number gewandelt werden. Lokalisierung, Währungssymbol und Nachkommastellen gehören an den passenden Formatter, nicht in den Enginebetrag. Aktuelle `read.status.money` und mehrere Engine-C++-Werte sind ganze Engine- Euro. Der Adapter konvertiert geprüft mit `10^minorUnits`; er interpretiert sie nicht als bereits vorhandene Centwerte. `ContractPlayer.current_monthly_salary` und `ContractRequest.monthly_salary` belegen Monatsgehälter; Jahreswert und Gesamtlaufzeit sind andere Felder. Quoten enthalten `totalBasis` und `chargesNow`: ein Monatsangebot ist keine sofortige Kontobuchung. Zinsbasis, Gebühren, Rundung, Aktienkurse, Mengen und Vertragspreise sind je Aktion abzugleichen. Kalendertage sind ISO `YYYY-MM-DD`; Saison-ID, Saisonlabel und Kalenderjahr bleiben getrennt. Historische Spieltage werden über `almanac_date()` übertragen. Dateizeitstempel benutzen UTC-`date-time`. Livezeit führt Periode, Minute und, nur wenn belegt, Sekunden/Nachspielzeit. Indoor- und Verlängerungsperioden dürfen nicht auf eine feste 0–90-Prozentachse gequetscht werden. Unklare historische Indoor-Perioden bleiben im Archivbeispiel ausdrücklich unbekannt. Für neue Live-Hallenspiele belegt `src/modern/game/driver.cpp` zwei 20-Minuten-Abschnitte; maßgeblich bleiben die gelieferten Periodenwerte der tatsächlichen Engine. Abwesenheiten führen Wert **und** Einheit: vorhandene Wochenzähler dürfen nicht still in exakte Verletzungstage oder Sperrspiele umgedeutet werden. ## Vier Manager und das neue Manager-Untermenü Der Sessionkontext enthält bis zu vier Personen und `activeManagerId`. `humanOwnership` ordnet Teams der aktiven menschlichen Kontrolle zu; eine archivierte Person ist keine aktive Kontrolle. Ein Team kann nicht durch eine veraltete Auswahl plötzlich einem anderen Manager gehören. Zwei menschliche Manager im selben Spiel ergeben zwei Eingriffsrechte, aber nur **ein** Match. Das neue Untermenü bündelt **Aufgeben**, **Vereinssuche** und **Neuer Spieler**. Die Vereinssuche ist vorerst eine als `future_readonly` erklärte Lesecapability. Neuer Spieler benutzt den bestehenden Join-Pfad und dessen gesperrte/belegte Plätze, keinen zweiten Startflow. Aufgeben zeigt eine revisionsgebundene Bestätigung: Bei weiteren Menschen übernimmt die KI das bisherige Team; beim letzten Menschen endet die Sitzung mit `last_human_resigned`. Identität, Amtszeiten und historische Titel bleiben im separat paginierten `manager_archive`. Das aktive Vier-Slot-Limit ist kein Limit für historische Personen. Das Ergebnis enthält AI-Handover, neue aktive Person oder `null`, `sessionState` und `terminationReason`. **Das ist der neue Nutzervertrag, keine hier implementierte Enginelogik.** Der neue HTML-Kontext `role` wird auf den DTO-Scope, `surface` auf das Matchformat und `managerPortrait` ausschließlich auf GUI-Porträtbindung abgebildet. Die Dummy-Porträtnummer erzeugt keine dauerhafte Engine-Manager-ID. Aktuell normalisiert HTML die Nationalrolle auf Outdoor; ein künftiger Enginecommand muss einen nicht unterstützten National-/Indoor-Kontext ausdrücklich ablehnen, statt eine andere Sportart heimlich zu simulieren. Die 0.3-Auswahl erlaubt derzeit deutsche Vereinsmanager und die belegte Deutschland-Nationalrolle; ausländische Clubs bzw. andere Nationaltrainer sind nicht pauschal als wählbar anzunehmen. Im National-Schreibtisch sind TOTO, Bank, Trainingslager, Training und Stadion durch den vorhandenen Enginekontext gesperrt (`ui/desk_state.cpp`); zusätzliche POC-Sperren für Sponsoren, Transfers, Verträge und Umfeld sind davon getrennte UI-Policy. `menuAvailability` trägt den konkreten Grund, statt nur `club=null` zu deuten. Der synthetische National- Managerfall steht für diese Deutschland-kompatible Rolle; andere Nationalteams bleiben als Gegner darstellbar. Indoor unterscheidet `rosterSize`, `rosterLimit`, `onFieldCount`, `onFieldLimit` und `benchLimit`. Belegt sind sechs gleichzeitige Feldpositionen und elf Zeilen im Rotationsplan (`game/lineup.cpp`); eine 11er-Feldregel aus der Outdooransicht darf nicht übernommen werden. `benchLimit=5` im Fixture ist die Partneraufteilung des synthetischen 11/6-Beispiels; sie erklärt keine allgemeine Kaderobergrenze, keine Aussage über einen neuen Wechselmodus. Wechselanzahl und Wiedereinwechselbarkeit bleiben D11. ## Pagination, Live und Nachspiel Listen haben max. 200 Zeilen pro Seite. Cursor sind opak und binden Filter, Sortierung, Owner, Revision und die letzte stabile ID. Sortieren findet vor dem Paginieren statt, gleiche Metrik hat einen ausdrücklich bestimmten Rang und ID-Tiebreak. Top-3-Karten und Restliste müssen denselben Snapshot verwenden. Ein alter Cursor führt zu `invalid_cursor`/Neuabfrage statt zu Mischständen. Das Schema validiert die Form, nicht die Serversemantik eines Cursors. Live liefert `presentationId`, `scopeToken`, monotone `sequence`, Match-/Event- IDs, beobachtete Spiele und Managerbezüge. Ein Managerwechsel, Nachspiel oder Halbzeitwechsel darf einen alten Eingriff nicht neu zuordnen. Verlorene oder falsch geordnete Deltas verlangen Resync; Wiederholung darf keine Tore doppeln. Präsentationspause/Abspieltempo und Engine-Fortschritt bleiben getrennt. Postmatch enthält die fünf vorhandenen HTML-Schritte Ergebnisse, Bericht, Elf des Tages, Übersicht und Tabelle. Rückblick/Seek verändert keine Saison. Nur `postmatch.continue` mit passendem Fortsetzungstoken darf die Engine genau einmal fortsetzen. Auszeichnungen und Tabellen sind autoritative Projektionen; keine UI-Torformel, 3-Punkte-Regel oder nominierte Elf wird nachgerechnet. Welche Schritte in Pokal/National/Indoor verfügbar sind, liefert Capability statt eines leeren, scheinbar fertigen Ligabilds. ## Übergabe und Abnahme Claude kann zunächst Umschlag/IDs/Einheiten und die P0-Entscheidungen festlegen, dann je Menü einen Sessionadapter samt Read-/Command-Tests liefern. Root bindet die native UI daran an. Die bestehenden Enginefunktionen und Classic bleiben hier unverändert. Je Lieferung sind Quelle, unterstützte Kontexte, Fehler, Revision, RNG-Unveränderlichkeit der Reads und atomare Negativfälle nachzuweisen. Eine bestandene Schema-QA bestätigt nur diesen Vertragsentwurf, keinen bereits lauffähigen Engineadapter, kein OBS-Migrationsformat und keine native Match-QA. Die Schemadatei und alle Beispiel-DTOs lassen sich ohne Engine oder Spieldaten mit den Generatoren unter `tools/` reproduzieren. Der Validator benötigt Python mit `jsonschema`; er validiert ausschließlich diese begrenzten Designfixtures.