# V4.4 — Neural Place

> **Hinweis:** Ab V4.5 wird die Place-Ökonomie zusätzlich durch Draw-, Aktivzeit- und Admin-Rewards erweitert. Siehe `V4.5_PLACE_REWARD_ECONOMY.md`.

Neural Place ergänzt den Hunt um eine gemeinsame, globale Pixel-Leinwand nach dem Grundprinzip von r/place. Anders als bei einem zeitbasierten Cooldown werden Placements ausschließlich durch echten Fortschritt im Hunt finanziert.

## Spielökonomie

- Solange Neural Place aktiviert ist, erzeugt jeder **dauerhaft gespeicherte Highscore-Fortschritt** eines Spielers Place-Punkte.
- Standard: **+1,00 Score-Prozentpunkte = 100 Place-Punkte**.
- Standard: **1 Placement = 100 Place-Punkte**.
- Kleine Score-Verbesserungen werden intern in Milli-Punkten gesammelt und gehen daher nicht durch Rundung verloren.
- Auch das Übermalen eines bereits belegten Pixels ist ein Placement und kostet Punkte.
- Es gibt **keinen Zeit-Cooldown**. Die knappe Ressource ist Hunt-Fortschritt.
- Vor dem Upgrade bereits vorhandene Scores werden absichtlich **nicht rückwirkend** vergütet. Punkte entstehen ab V4.4 bei neuen Verbesserungen.

Die Werte sind unter **Admin → RUNTIME** bzw. per Defaults konfigurierbar. Die Canvas darf erweitert werden; eine Verkleinerung wird abgewiesen, sobald dadurch bestehende Pixel außerhalb der neuen Grenzen lägen. Nach einer Größenänderung sollten offene `/place`-Seiten neu geladen werden:

```text
DEFAULT_PLACE_ENABLED=1
DEFAULT_PLACE_WIDTH=256
DEFAULT_PLACE_HEIGHT=256
DEFAULT_PLACE_POINTS_PER_SCORE=100
DEFAULT_PLACE_PIXEL_COST=100
```

## Hosted Worker / Account-Zuordnung

Neural Place verwendet die bestehende `identity_delegations`-Zuordnung. Erzielt ein mit einem Konto verknüpfter Hosted Worker eine echte Score-Steigerung, werden die Place-Punkte atomar dem Owner-Wallet gutgeschrieben. Der Worker bleibt im Fortschritts-Audit als Quelle sichtbar.

Damit können eigene Browser-/CLI-Fortschritte und Fortschritte mehrerer verknüpfter Worker dasselbe Place-Wallet finanzieren, ohne Worker-Identitäten zusammenzulegen.

## Konsistenz und Missbrauchsschutz

Die Punktevergabe läuft **in derselben SQLite-Transaktion wie die persistierte Score-Verbesserung**. Dadurch gilt:

- kein Reward für verlorene / nicht verbessernde Tipps,
- kein Reward für Lotterie-Tipps, die nicht ausgewertet wurden,
- kein doppelter Reward bei Retry oder parallelem Request,
- Score und Place-Punkte können nicht auseinanderlaufen,
- Worker-Owner-Auflösung erfolgt zum Zeitpunkt der erfolgreichen Verbesserung.

Die globale Leinwand verwendet eine monotone `revision`. Jedes Placement schreibt den aktuellen Pixelzustand und zusätzlich einen unveränderlichen Event-Eintrag. Das ermöglicht Live-Synchronisierung und Audit-Historie.

## Webinterface

`/place` ist die neue responsive Place-Oberfläche mit:

- zoombarer und verschiebbarer globaler Canvas,
- 32-Farben-Palette,
- Pixel-Auswahl mit aktuellem Besitzer und Revision,
- Wallet für Balance, erhaltene/ausgegebene Punkte und verfügbare Pixel,
- Anzeige der verknüpften Worker,
- Liste der letzten Hunt→Place-Vergütungen,
- Live-Placement-Feed,
- eigenem Place-WebSocket plus HTTP-Fallback-Synchronisierung,
- Desktop-, Tablet- und Mobile-Layout.

Die Canvas kann öffentlich gelesen werden. Für das Setzen eines Pixels ist die normale kryptografische Neural-Hunt-Identität/JWT-Sitzung erforderlich.

## Persistenz

Neue SQLite-Tabellen:

- `place_wallets` – Saldo, Lifetime-Einnahmen/-Ausgaben, Placement-Zähler,
- `place_state` – globale Canvas-Revision,
- `place_pixels` – aktueller Zustand jedes belegten Pixels,
- `place_pixel_events` – unveränderliche Placement-Historie,
- `place_progress_events` – Audit der Hunt→Place-Punktevergabe.

Die bestehende Admin-Profilbereinigung schützt ab V4.4 zusätzlich Identitäten mit verdientem Place-Wert oder Placements, damit ein Inaktivitäts-Cleanup keine erspielte Place-Ökonomie löscht.

## Neue HTTP-/WebSocket-Endpunkte

```text
GET  /api/public/place
GET  /api/public/place/changes?after=<revision>
GET  /api/place/ws
GET  /api/place/me            (User-JWT)
POST /api/place/pixel         (User-JWT)
```

Placement-Body:

```json
{"x": 12, "y": 34, "color_index": 15}
```

## Betrieb

Für große öffentliche Installationen kann die maximale Zahl der Place-WebSockets separat begrenzt werden:

```text
WS_MAX_PLACE_CONNECTIONS=1500
```

Die Place-Leinwand bleibt vollständig in SQLite persistent; ein Server-Neustart verliert weder Wallets noch Canvas noch History.