Add community map records and telemetry API; record Workshop 0.0.126

docs/telemetry.md

@@ -8,15 +8,34 @@ save-before-apply behavior also apply to this setting.
 
 Telemetry runs only on the mission authority, never independently on joining
 clients. Workbench runs do not collect unless explicitly launched with the
-`errTelemetryTest` diagnostic flag. There is no statistics website or production
-receiver included in this change.
+`errTelemetryTest` diagnostic flag. A deployable Cloudflare Worker/D1 receiver is
+provided in [services/telemetry-worker](../services/telemetry-worker/README.md).
+It includes automatic server enrollment and protected mission/player query APIs.
+The Worker must be deployed separately. There is no statistics website.
 
 ## Receiving URL and configuration
 
-The bundled receiving URL belongs in `addons/core/Configs/ERR/Telemetry.conf`.
-It is currently empty pending the receiver's actual URL. Until configured, no
-telemetry is collected or sent, even with the switch enabled. The menu reports
-this condition rather than claiming that statistics are being delivered.
+The bundled receiving URL in `addons/core/Configs/ERR/Telemetry.conf` is
+`https://co10escape-telemetry.zacekjakub.workers.dev/api/mission-events`.
+Any host running the updated mission can report without contacting the receiver
+administrator or editing its configuration. Mission → Statistics remains the
+administrator opt-out. This source change requires a new Workshop release;
+0.0.125 does not contain automatic enrollment.
+
+Before the first request, the host saves its own randomly generated credential
+in `$profile:EscapistsTelemetryCredentials.json`. The Worker enrolls an unknown
+server ID on its first valid event and stores only the credential hash. Later
+requests must present the same credential. Enrollment and the initial event are
+committed together. Disabling telemetry prevents enrollment and delivery and
+discards pending events; the credential remains for continuity when re-enabled.
+No shared secret or receiver administrator credential is bundled in the mod.
+
+Keep the credentials file with the profile state when moving a server. Damaged
+credentials suspend delivery without silently rotating them. The file retains
+up to 16 server/endpoint pairs, so changing receiving URLs does not send one
+receiver's secret to another. Explicit operator-issued tokens still override
+automatic credentials. The default receiver accepts community reports, not
+independently verified gameplay or identities.
 
 An operator can override the URL and optionally name/authenticate their instance
 with `$profile:EscapistsTelemetry.json`:
@@ -31,8 +50,9 @@ with `$profile:EscapistsTelemetry.json`:
 
 Use the full POST endpoint, with its exact trailing-slash convention. HTTPS is
 required. URL credentials, fragments and query parameters are rejected. The
-optional token goes in the HTTPS JSON body, never in a URL, menu snapshot, log,
-Workshop resource, or persisted event queue. Configuration loads when the mission
+explicit or automatically generated token goes in the HTTPS JSON body, never in
+a URL, menu snapshot, log, Workshop resource, or persisted event queue.
+Configuration loads when the mission
 starts. An empty endpoint overrides the bundled default and prevents sending.
 
 `serverId` is a generated UUID persisted in
@@ -128,6 +148,23 @@ precision), not survival time. Reconnects reuse the authenticated identity.
 
 ## Reliable ingestion and aggregation
 
+The default receiver also returns public map aggregates from `GET /api/summary`
+(and `GET /api/mission-events`). `terrain` filters the actual world resource;
+`serverId` adds the installation's record for that map. Summaries expose counts
+only; detailed player and mission records still require a read/admin token.
+
+After durably accepting a victory or defeat, the Worker returns a `community`
+summary containing matching map/server/mission/event/outcome identifiers plus
+`server` and `allServers` records. Each record has completed rounds, wins,
+failures, win rate and partial-round coverage. The mission validates these
+identifiers and counts before displaying the current map's record on its result
+screen. Retries never increase the totals twice. Startup failures, interrupted
+sessions and empty restarts are excluded from win/failure totals. If a summary
+cannot be delivered before the next mission starts, the screen reports it as
+unavailable and keeps local statistics visible.
+Once a confirmed record is displayed, failures uploading older queued events
+cannot replace it with the unavailable message.
+
 Return any **2xx only after durable storage**, including for an already accepted
 event. Other responses/timeouts retry the identical event with the same event ID.
 The receiver must enforce uniqueness on `(serverId, eventId)` and aggregate by
@@ -154,9 +191,11 @@ Useful queries from terminal mission snapshots:
 - Milestone times: phase-event elapsed time differences for prison, radio and
   extraction. Treat missing phases, dropped events and partial runs as unknown.
 
-Validate schema and limits and authenticate operator-issued tokens if statistics
-must be trusted. The bundled addon contains no shared secret. These are reports
-from community-hosted missions, not independent anti-cheat attestations.
+The Worker validates schema and limits and binds each server to its private
+credential after the first accepted event. Automatic enrollment proves continuity
+of a claimed installation, not its operator's identity or gameplay honesty.
+Operator-created server records are labelled separately. These are reports from
+community-hosted missions, not independent anti-cheat attestations.
 
 ## Buffering, disabling and limits