DEPLOYMENT.md

1# LittlePly local serving
2
3Initial public admission is **one casual standard-start game**, clocks 10–30 minutes with 5–30 second increments. No challenges are sent, no matchmaking runs, and chat text is ignored. Both GPUs are invisible to serving. Four CPU threads and a 6 GiB service memory ceiling leave GPU memory available for training. CPU contention can still increase latency; the offline timings are not a training-load guarantee.
4
5The existing Ubuntu systemd supervises a dedicated runtime copy and a content-addressed source/checkpoint release. `littleply.service` restarts failures after 15 seconds, caps repeated failures, and watches the nonblocking main loop. This remains dependent on Windows and WSL being awake/running; no external host or cloud availability is implied. The service does not change credentials, account settings, or firewall rules.
6
7The local Windows scheduled task uses native `wsl.exe -d Ubuntu --exec /bin/sleep infinity` under the existing interactive user with limited privileges, starts at that user's logon, and keeps WSL awake. It cannot serve while Windows is asleep/off or before login. The original PowerShell-script task action failed and was replaced by the native action without changing execution policy. The repository's `keepalive.ps1` is an optional example, not the installed action. The actual `littleply.service` contains host-specific paths and must not be included in a public source bundle; publish a parameterized service example instead.
8
9One event-loop owner controls game state and one inference owner controls keyed worker IPC. Separate bounded HTTP and stream threads keep requests/backoff out of model execution. Every inference response is matched to game ID, stream epoch and complete history digest. Histories never crop. The CPU scorer prefills the complete history once and uses fresh KV branches for all legal tails; raw 128-class diagnostics remain unmasked. A three-ply proof precedes model scoring, with separate PGN annotations and no fabricated model probabilities. A deadline/crash fallback is explicitly labelled and closes further admissions until a successful model decision.
10
11HTTP 429 imposes shared backoff of at least 60 seconds. Known rejection and uncertain writes differ. An uncertain move can retry only the same journalled move after a fresh unchanged server snapshot, at most three attempts. HTTP authentication failure stops the service. Account resynchronization releases abandoned challenge reservations; duplicate, shorter and divergent game histories are ignored. Stream epochs increase across reconnects. The singleton lock is shared for the account deployment. Log files rotate at 5 MB with three backups; low disk space closes admissions. Active PGNs are private.
12
13Each game journal pins its checkpoint release hash. Releases include hashes of checkpoint, tokenizer and runtime source files; startup fails closed on tampering. Promotion/rollback must close admissions, drain active games, stop the service, select a verified retained release atomically, and restart. There is no automatic following of training's mutable best.pt and no mid-game model switch. A mismatched pinned game blocks startup rather than silently using different weights.
14
15`prepare_release.py --checkpoint-sha256 <approved hash>` stages an explicitly chosen checkpoint. `promote.py` also checks the server's active-game list after draining, because local status can be stale after a crash. If the server cannot confirm no active game, it leaves the old release pointer unchanged and stops; the operator can resume that pinned release. Retained releases permit the same explicit drain-and-promote rollback procedure.
16
17Create `state/drain` to stop accepting and finish the current game. Removing it alone does not launch a stopped service. SIGTERM also drains; systemd allows six hours for completion before its hard shutdown bound. Host power loss cannot preserve an active connection; restart reconciles server history and the saved move journal. `state/health.json` reports readiness, admission, active game, release, process IDs and rate-limit cooldown. Never publish private state, tokens, or human PGNs without approval.
18
19Validation evidence is recorded in `cpu-probe.json`, `worker-probe.json`, and offline unittest output. CPU probe included a 985-token history; cached/reference parity checks are numerical (1e-4 log-score tolerance), not a promise of bit-identical floating-point kernels on every machine.
20