feat(scum): add map trajectory projection

openspec/changes/add-scum-map-trajectories/specs/scum-map-trajectories/spec.md

@@ -0,0 +1,59 @@
+## ADDED Requirements
+
+### Requirement: Controlled SCUM trajectory event contracts
+The system SHALL accept SCUM location information only as platform-managed Companion or accepted log-projection semantic events named `player.position`, `vehicle.position`, `player.vehicle.enter`, and `player.vehicle.leave`, each carrying bounded IDs, occurrence and collection timestamps, declared source, and matching map metadata.
+
+#### Scenario: An undeclared or malformed location event arrives
+- **WHEN** an event has an unknown type, malformed bounded ID, non-finite coordinate, invalid source, or mismatched map declaration
+- **THEN** the system SHALL reject it from trajectory projection and SHALL not expose raw event material to the browser
+
+### Requirement: Plugin-declared safe map conversion
+The SCUM plugin SHALL declare a map ID/version, coordinate transform/world bounds, sampling precision, and finite retention period. The platform SHALL convert accepted world points into a rounded safe map projection before persistence or API delivery.
+
+#### Scenario: A point is outside declared map bounds
+- **WHEN** a valid position event has world coordinates outside the declared transform bounds
+- **THEN** the platform SHALL not persist or return a map point for that event
+
+#### Scenario: Map metadata is absent
+- **WHEN** a server plugin has no compatible map declaration
+- **THEN** the map API and console SHALL return a readable missing-map state without attempting alternative collection
+
+### Requirement: Ordered, sampled, and retained server-isolated trajectories
+The system SHALL index points by server, entity, and occurrence time; tolerate duplicate and out-of-order events; apply declared sampling compression; and remove points and closed ride segments after the declared retention period.
+
+#### Scenario: Duplicate or delayed position event
+- **WHEN** the same accepted event is delivered twice or an older point arrives after a newer point
+- **THEN** the system SHALL retain no duplicate and SHALL return all accepted points ordered by occurrence time without regressing current sampling state
+
+#### Scenario: A point is below the sampling threshold
+- **WHEN** a same-entity point occurs inside the declared minimum time and distance thresholds
+- **THEN** the system SHALL compress it rather than persist another display point
+
+#### Scenario: Retention expires
+- **WHEN** normal projection or map retrieval occurs after a point or closed riding segment passes its retention deadline
+- **THEN** the system SHALL remove the expired record while preserving unrelated player identity and vehicle snapshot data
+
+### Requirement: Vehicle ride association
+The system SHALL derive player vehicle segments from typed enter/leave events and SHALL close a prior active segment before opening a segment for a different vehicle.
+
+#### Scenario: A player changes vehicles without a leave event
+- **WHEN** a player enters a second vehicle while a first vehicle segment remains active
+- **THEN** the system SHALL close the first segment at the second enter time and open one segment for the second vehicle
+
+### Requirement: Authorized bounded map read model
+The system SHALL authorize server access before returning a maximum 24-hour trajectory window and SHALL expose only safe projected points, declared map metadata, collection/source labels, entity summaries, and detail-link identifiers. It SHALL not expose raw coordinates, raw logs, IPs, paths, credentials, host information, or Run/Companion connectivity.
+
+#### Scenario: Unauthorized map request
+- **WHEN** a session lacks access to the requested server instance
+- **THEN** the API SHALL deny the request without revealing map availability, entity existence, or trajectory data
+
+#### Scenario: Cross-server entity selector
+- **WHEN** a requested player or vehicle ID belongs only to another server
+- **THEN** the response SHALL not include its points or reveal the other server association
+
+### Requirement: Explainable SCUM map console
+The SCUM console SHALL render declared map metadata, collection source/times, selected player and vehicle points/lines, ride segments, time and entity filters, and textual empty or missing-map states. Map entity interactions SHALL use the returned safe detail-link identifiers.
+
+#### Scenario: An operator selects a trail entity
+- **WHEN** an operator selects a player or vehicle map item
+- **THEN** the console SHALL navigate or invoke the matching player/vehicle detail context using the returned identifier without constructing arbitrary coordinate or data queries