browser/openspec/changes/replace-scum-projections-with-real-data-management/specs/scum-realtime-map/spec.md

ADDED Requirements

Requirement: Independently verified current map facts

The system SHALL store and present current player, vehicle, flag, and squad-territory coordinates only when each resource's plugin adapter maps a compatible current-service source, identity, coordinate, and observation time.

Scenario: One position resource is incompatible

• WHEN player and flag positions are compatible but the vehicle query lacks a required column, type, identity, or unique join
• THEN Platform keeps the verified player/flag layers available, disables only the vehicle layer, and SHALL NOT return an empty vehicle list as a successful current result

Scenario: Vehicle ownership is unverified

• WHEN the source proves a vehicle identity/class and coordinate but does not prove a player or squad owner
• THEN Platform stores the verified fields and leaves ownership null instead of inferring it from nearby players, movement history, or an expiry heuristic

Scenario: Position scan later fails

• WHEN verified positions were previously stored and a later current-service scan fails or is partial
• THEN the map may retain the last completed rows with their concrete collection time and connection interruption, but SHALL NOT call them current or replace them with empty/generated points

Requirement: Declared SCUM map asset and coordinate transform

The realtime map SHALL use a plugin-declared distributable map asset/version and integrity digest, verified world bounds, and a tested coordinate transform version/digest compatible with the current SCUM adapter.

Scenario: Verified coordinate is rendered

• WHEN a player, vehicle, flag, or territory coordinate falls within the declared bounds and transform version
• THEN the map places the marker at the tested map position and shows object type, name/ID, source coordinate, and collection time

Scenario: Map metadata is incompatible or absent

• WHEN the map asset, version, bounds, or transform does not match the current server adapter
• THEN the map shows a readable unavailable/error state and SHALL NOT fall back to a gradient board, arbitrary percentage transform, fake points, or sample routes

Scenario: Map asset digest does not match

• WHEN the packaged/browser-served map asset or transform contract fails its plugin-declared integrity check
• THEN the map is unavailable and SHALL NOT render coordinates against an unverified replacement asset

Scenario: Coordinate is outside bounds

• WHEN a source coordinate is non-finite or outside the declared world bounds
• THEN Platform rejects it from the current map dataset and records a bounded validation failure

Requirement: Automatically updated and distinguishable map layers

The realtime map SHALL consume platform-local data automatically and provide distinguishable player, vehicle, and flag/squad-territory layers with player/squad filtering.

Scenario: Operator changes layer visibility

• WHEN an operator toggles players, vehicles, or flags/territory or applies a player/squad filter
• THEN the map updates the visible verified markers without dispatching a Run query or manual refresh operation

Scenario: Platform receives a newer coordinate

• WHEN a verified automatic sync or declared companion position event updates a current position
• THEN Platform publishes a safe local update and the open map can update through the platform event stream

Scenario: Source cadence is insufficient

• WHEN measured SCUM.db updates cannot support the declared realtime threshold
• THEN the plugin uses a declared verified companion position source or the feature presents the measured cadence honestly; it SHALL NOT increase unsafe polling or fabricate intermediate movement

Scenario: Map legend is rendered

• WHEN multiple entity types are visible
• THEN the UI provides icons or textual legend labels so entity meaning does not rely only on color

Scenario: Historical movement was not requested

• WHEN only current positions are available under this change
• THEN the product SHALL NOT fabricate trajectories, 24-hour trails, ride associations, sampling history, or playback controls to satisfy realtime-map acceptance

Requirement: Server-isolated realtime-map API

The realtime-map API SHALL authorize the target server and return only bounded local current-position and safe object-summary fields needed by the map.

Scenario: Foreign map selector is supplied

• WHEN a player, squad, vehicle, flag, or territory selector belongs only to another server
• THEN Platform returns no foreign marker and does not reveal its existence or server identity

Scenario: Browser requests protected source material

• WHEN a browser attempts to request raw database rows, SQL, host paths, database identifiers, map-source credentials, or Run connection details
• THEN the API rejects the request and returns only named safe map fields