Release - v0.48.0 - GPS Integrity Monitoring + Poller Health + OpenSky Robustness

This release introduces comprehensive GPS integrity jamming detection with AI analysis support, real-time poller health monitoring across all data sources, and improved OpenSky API resilience for reliable global aircraft tracking. The frontend receives improved modularity through dedicated entity processing engines, and the backend gains enterprise-grade health observability.

High-Level Summary

v0.48.0 shifts the platform toward intelligent signal-integrity awareness and operational health visibility. When the aviation poller detects correlated GPS degradation (low NIC/NACp clusters in H3 cells), jamming zones now render on the map with full AI analyst support. Operators see real-time health status for all 12 poller types—tracking whether each source is current, stale, errored, or missing credentials. The OpenSky client now handles rate-limiting gracefully with separate pacing for bbox vs. watchlist queries and automatic respect for server-provided Retry-After headers.

Key Features

GPS Integrity Jamming Detection (End-to-End)

• Map Rendering: Active jamming zones render as styled ScatterplotLayer features with pulse animation and hover tooltips.
• Sidebar Analysis: Click any zone to open detailed analysis panel with confidence trends, affected track counts, and NIC/NACp metrics.
• AI Integration: Jamming entities flow through the analysis router with synthesized track summaries for tactical AI comments.
• Trend Visibility: 24-hour confidence sparkline with +/− trend delta shows jamming intensity movement over recent incident history.
• Filter Management: GPS Integrity Zones toggles in both tactical (environmental group) and orbital (quick pills) views.

Poller Health Monitoring

• Real-Time Dashboard: SystemHealthWidget displays status for 12 pollers across 5 categories (Tracking, Orbital, Environment, Intel, RF, Infrastructure).
• Status Indicators: Visual feedback for healthy (green), stale (amber), error (red), no-credentials (gray), and pending (neutral) states.
• Timestamp Visibility: Human-readable "last success" and "last error" ages so operators know data freshness at a glance.
• Credential Validation: Health checks verify environment variables and API keys are configured for each poller.
• Stale Detection: Per-poller thresholds (5 min for real-time tracking, 30 days for reference data) detect stalled ingestion.

OpenSky API Robustness

• Separate Rate Limiters: Independent OPENSKY_WATCHLIST_RATE_LIMIT_PERIOD for slower testing pacing (e.g., 120s watchlist vs. 22s bbox).
• Retry-After Compliance: Client automatically honors OpenSky's Retry-After response header, reducing hammering during transient limits.
• Cooldown Escalation: Consecutive penalties now escalate properly even when retries occur after cooldown expiry.
• Error Logging: All poller errors logged to Redis with throttled heartbeat to centralize observability.

Frontend Modernization

• Entity Processing Engines: Extracted EntityFilterEngine.ts and EntityPositionInterpolator.ts to improve code organization and testability.
• Layer Visibility Extraction: LayerVisibilityControls.tsx consolidates map layer UI logic for easier iteration.
• System Status Refactor: SystemStatus.tsx now focuses on orchestration with delegated layer/integration concerns.
• Intelligence Feed Throttling: 1-second per-category throttle reduces "wall of text" visual noise while preserving critical alert immediacy.

Technical Details

GPS Integrity Jamming (Backend Flow)

1. Aviation poller ingests ADS-B with NIC/NACp fields from ADSBx/OpenSky.
2. JammingAnalyzer detects correlated degradation in H3-6 cells; confidence scored by NIC severity + Kp geomagnetic activity.
3. Zones published to Redis key jamming:active_zones with 10-minute TTL (auto-refreshed on each detection).
4. Frontend queries /api/jamming/active and /api/jamming/history?hours=24 for map rendering and sidebar sparkline.
5. Analysis router fallback recognizes jamming-<h3> UIDs and synthesizes track_summary from Redis + history.

Jamming Assessment Types

• jamming: High confidence, low Kp → Likely intentional/localized interference.
• space_weather: Low confidence, high Kp → Solar activity driving ionospheric degradation.
• mixed: Elevated Kp + mid-range confidence → Blended causes.
• equipment: No area clustering → Single-receiver fault (receiver error, antenna issue).

Poller Health Architecture

• Each poller writes heartbeat to Redis key <poller>:last_fetch with timestamp and optional error text.
• Errors logged to <poller>:error with throttled writes (min 30s interval to reduce Redis load).
• Health endpoint queries Redis state + validates environment credentials; frontend consumes /api/config/poller-health on demand.
• Stale thresholds are per-poller (e.g., ADSB: 5 min; FCC towers: 30 days; SatNOGS TLE: 1 day).

OpenSky Client Improvements

• Separate AsyncLimiter instances for bbox and watchlist ensure independent rate-limit compliance.
• Watchlist mode can use slower pacing (e.g., 120s) for testing without affecting local bbox queries.
• Retry-After handling: client sleeps before next request if server specifies delay.
• Cooldown state properly escalates across penalty attempts, preventing repeated hammering.

Dependency Security

• New audit script (tools/audit-deps.sh) scans 7 components for CVEs across uv (6 Python projects) and pnpm (1 Node.js project).
• Frontend overrides for flatted and fast-xml-parser patched to known-safe versions.
• CI workflow now runs audit-deps.sh as part of security checks.

Upgrade Instructions

1. Pull & Checkout

git pull origin main
git checkout main  # or your deployment branch

2. Frontend Verification & Build

cd frontend
pnpm install  # if lockfile changed
pnpm run lint && pnpm run test
docker compose build sovereign-frontend

3. Backend Verification & Build

cd backend/api
python -m pytest
python -m pytest backend/ingestion/*/tests  # poller unit tests

4. Environment Configuration (Optional)

If testing OpenSky watchlist with custom rate limits, add to .env:

OPENSKY_ENABLED=true
OPENSKY_WATCHLIST_ENABLED=true
OPENSKY_RATE_LIMIT_PERIOD=22          # bbox queries (default: auth=22s, anon=300s)
OPENSKY_WATCHLIST_RATE_LIMIT_PERIOD=120  # watchlist queries (optional, defaults to bbox)

5. Restart Services

# Stop all services
docker compose down

# Rebuild & restart with new code
docker compose up -d --build

# Verify all services are healthy
docker compose ps

6. Validate Health Monitoring

1. Open the map UI.
2. Click the System Health widget (top-right corner).
3. Verify all poller statuses (healthy/stale/error) display and update when widget is open.
4. Check one poller in docker compose logs <service> to confirm error logging to Redis.

7. Test Jamming Detection

1. In the tactical view, ensure GPS Integrity Zones toggle is ON in settings.
2. If live ADS-B shows GPS degradation, zones will render on map.
3. Click any zone to open right-sidebar jamming analysis.
4. Verify confidence sparkline loads (or shows "No trend history" if <24h data).
5. Click "Analyze" button to see AI analyst comments.

Breaking Changes

None. All API endpoints and TAK protocol remain backward-compatible. Existing clients will continue to function; GPS integrity features are opt-in via UI toggles.

Performance Notes

• Jamming analysis runs every 30 seconds (configurable via _jamming_analysis_interval in PollerService).
• Health endpoint caches Redis state for 10 seconds to reduce polling overhead.
• Entity filtering uses separate workers for staleness checks, reducing main render thread load.

Known Limitations

• Jamming sparkline history: Requires events in jamming_events database table; synthetic test data does not persist without manual database injection.
• OpenSky watchlist: First-run sync can be slow if many ICAO24s are queued; consider seeding with targeted affiliation types.
• Poller health: Stale thresholds are hardcoded per source; future releases may expose as environment variables.

Support & Feedback

• Bug Reports: Check existing task logs in agent_docs/tasks/ for known issues.
• Feature Requests: Report via standard PR workflow with context in issue templates.
• Deployment Issues: Consult Documentation/Deployment.md or CI logs in .github/workflows/.

---

Release Date: 2026-03-25
Stability: Stable (production-ready)
Components Tested: Frontend (lint + 36/36 tests), Backend API (23 passed), Ingestion (unit tests), CI (smoke workflow)

Release - v0.47.2 - Settings Modularity + Preset Expansion

This release focuses on operator workflow speed and maintainability in the tactical settings stack. The System Settings and Listening Post flows were decomposed into focused modules, and new quick presets were added to switch instantly between orbital-only and terrestrial map-layer views.

High-Level Summary

The frontend now treats System Settings and JS8 Listening Post concerns as composable building blocks instead of monolithic components. At the same time, filter preset coverage was expanded so operators can move between space-only and map-only perspectives with one click while keeping clear/all behavior consistent.

Key Features

• New Presets: Added Orbital Only and Map Layers presets in frontend/src/components/widgets/FilterPresets.tsx.
• Settings Refactor: Decomposed SystemSettingsWidget responsibilities by extracting watchlist/state concerns into frontend/src/hooks/useWatchlist.ts and frontend/src/components/widgets/WatchlistManager.tsx.
• Listening Post Refactor: Extracted KiwiSDR configuration constants into frontend/src/components/js8call/kiwi/RadioModeConfig.ts and frontend/src/components/js8call/kiwi/WaterfallColorMaps.ts and wired ListeningPost.tsx to consume them.
• Search UX Accessibility: Improved frontend/src/components/widgets/SearchWidget.tsx accessibility with stronger labeling and clear-action semantics.

Technical Details

• Filter Key Coverage: Preset management now includes showSatNOGS, showH3Coverage, and showTerminator for consistent all/clear transitions.
• Risk Reduction: Splitting settings and listening-post concerns reduces coupling, improves testability, and lowers regression risk during future UI iteration.
• No Protocol Changes: No TAK schema or backend API contract changes are introduced in this release.

Upgrade Instructions

1. Pull latest refs and checkout the release branch tip.
2. In frontend/, install dependencies if needed: pnpm install.
3. Run verification: pnpm run lint && pnpm run test.
4. Rebuild runtime image for parity checks: docker compose build sovereign-frontend.
5. Restart frontend service: docker compose up -d --build sovereign-frontend.

Release - v0.47.1 - Frontend Modularization

This release improves the internal architecture of the frontend intelligence pipeline by extracting key logic from monolithic components and hooks into dedicated, reusable modules. The primary value is higher maintainability and testability with behavior preserved for operators.

High-Level Summary

The dashboard and entity-worker paths were refactored to separate concerns across alert engines, domain filters, widgets, and worker protocol handling. Inline logic that previously lived in DashboardView, IntelFeed, and useEntityWorker is now encapsulated in focused modules, reducing complexity and making future changes safer.

Key Features

• Alert Engines: Introduced AviationAlertEngine.ts and MaritimeAlertEngine.ts to centralize emergency/distress detection and normalized alert message construction.
• Domain Event Filters: Added dedicated filtering modules for aviation, maritime, and orbital streams (AviationEventFilter.ts, MaritimeEventFilter.ts, OrbitalEventFilter.ts).
• Widget Extraction: Split dashboard widget responsibilities into reusable components: MiniMap, StreamStatusMonitor, OutageAlertPanel, RFSiteSearchPanel, and TrackSparkline.
• Worker Protocol Isolation: Added WorkerProtocol.ts to encapsulate worker initialization, WebSocket lifecycle management, and reconnect behavior.
• Shared Utilities: Added trailSmoothing.ts and EventCategorizer.ts for reusable smoothing/styling behavior across feed and map contexts.

Technical Details

• Behavior Preservation: Refactor is intentionally non-breaking at runtime; extracted modules preserve existing UI and alert behavior.
• Complexity Reduction: useEntityWorker.ts and DashboardView.tsx now act as orchestration layers with less inline logic and tighter module boundaries.
• Consistency Gains: Unified event filtering and style categorization reduce drift risk across air, sea, and orbital event rendering paths.
• No Protocol Changes: No TAK protocol schema or backend API contract changes were introduced in this release.

Upgrade Instructions

1. Pull the latest branch and update local refs.
2. In frontend/, install dependencies if needed: pnpm install.
3. Run frontend verification: pnpm run lint && pnpm run test.
4. Rebuild and restart the frontend service for runtime parity: docker compose up -d --build sovereign-frontend.

Release - v0.47.0 - Shadow Pulse Optimization

This update focuses on situational awareness and interface refinement. We have optimized the intelligence streams to provide a cleaner, more actionable data flow while unifying the visual identity of orbital surveillance assets.

High-Level Summary

Operators will notice a significantly more stable intelligence feed during high-intensity operations, as we have introduced a rate-limiting throttle for general events while preserving the immediacy of tactical alerts. The dashboard and orbital widgets now share a consistent purple aesthetic for ISR satellite assets, and the Global Situation view provides a distraction-free overview by removing geographical labels.

Key Features

• Intelligent Event Throttling: Added a 1-second per-category throttle for 'New' and 'Lost' entity events in the main HUD. Tactical and critical alerts bypass this throttle for zero-latency awareness.
• ISR Asset Rebranding: Standardized the 'PassPredictor' and 'Dashboard' orbital grids with a purple accent theme to distinguish Intelligence/ISR satellites from general space debris and constellations.
• Situational Globe Overhaul: Removed clutter by filtering out country and place-name labels from the primary SIT-GLOBE, improving clarity for infrastructure and orbital overlays.

Technical Details

• Frontend Performance: Reduced CLI spam and DOM churn by implementing a useRef-based throttling pattern in the central event bus.
• MapLayer Optimization: Integrated style-layer filtering in the MapLibre adapter to dynamically prune basemap labels.
• State Integrity: Resolved cascading JSX errors that previously impacted the dashboard's pass-predictor grid during constellation transitions.

Upgrade Instructions

1. Pull the latest main branch.
2. Run pnpm install in the frontend/ directory to sync metadata.
3. Rebuild the frontend container: docker compose up -d --build sovereign-frontend.

Release - v0.46.3 - Sidebar Modularization & GDELT Fidelity Fixes

High-Level Summary

This patch release focuses on maintainability and intelligence-display correctness. The right sidebar has been decomposed from a monolithic component into focused domain views with explicit shared types, and GDELT actor/tone rendering has been corrected end-to-end so sidebar and tooltip metrics match backend payloads and map color semantics.

Key Features

• SidebarRight Decomposition: Split the previous 1,866-line SidebarRight.tsx into focused view modules under sidebar-right/:
  • JS8View, RepeaterView, TowerView, InfraView, GdeltView, SatelliteView, ShipView, AircraftView.
• Thin Orchestrator Pattern: SidebarRight.tsx now routes by entity type and passes key={entity.uid} to each view, eliminating previous prevUid / state-reset anti-patterns.
• Shared Sidebar Contracts: Added sidebar-right/types.ts with BaseViewProps, SatelliteViewProps, AircraftViewProps, InfraDetail, and InfraProperties.
• GDELT Actor 1 Integrity: actor1 is now included in backend GeoJSON properties and mapped through frontend GDELT layer typing.
• Tooltip Metric Consistency: GDELT TONE (GS) and STATUS now use Goldstein scale (goldstein) instead of average tone (tone), matching map dot color logic.

Technical Details

• Frontend:
  • Refactored sidebar detail rendering into per-domain components under frontend/src/components/layouts/sidebar-right/.
  • Added per-view local state ownership and deterministic state reset on entity change via key={entity.uid}.
  • Updated GDELT layer interfaces/mapping to include actor1 in GdeltFeature.properties and GdeltPoint.
  • Updated MapTooltip.tsx GDELT section to drive value/status thresholds from goldstein and use nullish coalescing for zero-safe display.
• Backend API:
  • Updated backend/api/routers/gdelt.py GeoJSON property mapping to include "actor1": r["actor1"].

Upgrade Instructions

1. Pull latest source and tags

   git pull origin main --tags

2. Rebuild and restart affected services

docker compose up -d --build sovereign-backend sovereign-frontend sovereign-nginx

3. **Run targeted frontend verification**
```bash
cd frontend
pnpm run lint
pnpm run test

4. Run targeted backend API verification

cd backend/api
ruff check .
python -m pytest

5. Validate GDELT API payload shape (optional sanity)

   curl "http://localhost/api/gdelt/events?refresh=true&limit=5"

Release - v0.46.2 - GDELT Enrichment & Stability

High-Level Summary

This patch release hardens Sovereign Watch's GDELT intelligence pipeline from ingestion through UI analytics. GDELT events now carry richer geopolitical context (actors, countries, class, media intensity), the Analyst workflow can reason directly over GDELT selections, and frontend map/label behavior is safer and clearer under malformed or sparse source data conditions.

Key Features

• Full GDELT Metadata Enrichment: Added actor/country/event-class/media fields across poller, historian, database schema, API, and map layers.
• Stable GDELT Entity IDs: Replaced headline substring UIDs with event_id identifiers to prevent collisions and improve entity continuity.
• Analyst GDELT Fallback: Added dedicated GDELT fallback context in the analysis router with geopolitical persona specialization.
• Independent Domain Tag Toggle: Added a separate GDELT label toggle in the Global Event Tracking footer control.

Technical Details

• Database:
  • Added actor1_country, actor2_country, event_code, event_root_code, quad_class, num_mentions, num_sources, num_articles, event_date to gdelt_events.
• Ingestion:
  • Poller now extracts enriched columns and resolves SOURCEURL using last-column strategy to tolerate GDELT schema drift.
• Historian:
  • Upsert query expanded for enriched fields and fixed event_date casting/type inference path.
• API:
  • /api/gdelt/events now exposes enriched properties and validated domain extraction for labels/source links.
• Frontend:
  • Sidebar and tooltip now display event class, actor countries, and media metrics.
  • Domain labels are readability-tuned and default to OFF, with explicit user toggle.

Upgrade Instructions

1. Pull latest source and tags

   git pull origin main --tags

2. Rebuild and restart affected services

   docker compose up -d --build sovereign-gdelt-pulse sovereign-backend sovereign-frontend sovereign-nginx

3. Verify frontend compile health

   cd frontend
   pnpm run verify

4. Validate GDELT API payload shape (optional sanity)

   curl "http://localhost/api/gdelt/events?refresh=true&limit=5"

Release - v0.46.1 - Bug Squash Hardening

High-Level Summary

This patch release is a large-scale stabilization pass focused on reliability and developer velocity. The frontend now enforces TypeScript compiler checks in the standard workflow, and a broad set of map/layer/infrastructure type contract issues were resolved. The result is a significantly cleaner Problems panel, safer runtime event handling, and fewer regressions slipping through lint-only validation.

Key Features

• Typecheck Workflow Added: Frontend now includes pnpm run typecheck and pnpm run verify to gate both lint and compiler checks.
• Massive Bug Squash: Type and contract fixes across tactical/orbital map rendering, tooltip data shaping, replay utilities, and JS8 websocket payload parsing.
• Deck.gl Typing Alignment: Path/polygon accessors and pick-info adapters updated to match strict Deck v9 typings.
• Map Callback Hardening: Unknown event payloads are safely narrowed before property access in map movement/load flows.

Technical Details

• Frontend Script Changes:
  • Added typecheck: tsc --noEmit
  • Added verify: pnpm run lint && pnpm run typecheck
• Compiler Diagnostics: Resolved the previously uncaught TypeScript backlog in frontend hooks, map components, and layer builders.
• Version Metadata: Frontend package bumped to 0.46.1.

Upgrade Instructions

1. Pull the latest changes:

   git pull origin main --tags

2. Rebuild frontend/backend containers:

   docker compose up -d --build sovereign-frontend sovereign-backend

3. Run verification:

   cd frontend
   pnpm run verify
   pnpm run test -- --run

Release - v0.46.0 - OSINT Convergence & Orbital Refinement

High-Level Summary

This release marks the full integration of the GEODENT (GDELT Pulse) data pipe, transforming Sovereign Watch into a unified tactical and OSINT monitoring platform. Operators can now monitor global stability via real-time news events from the GDELT Project, fused directly into the intelligence stream alongside aviation and maritime telemetry. Additionally, this update refines the orbital visualization suite, ensuring that satellite mission timing and space weather metrics are perfectly aligned within the high-fidelity HUD.

Key Features

• GEODENT (GDELT): Real-time global event ingestion (every 15 mins) providing tactical context via conflict, protest, and diplomatic reports.
• Orbital HUD Refinement: Repositioned the Polar Plot geometry widget to prevent overlap and improved visual coherence with the Space Weather monitor.
• Intelligence Stream Fusion: GDELT headlines are now fully interactive, allowing users to "Fly To" OSINT event locations and identify nearby tactical assets with a single click.
• Default Terminator Logic: Synchronized day/night terminator visibility across all map projections by default.
• Stabilized UI Loop: Resolved critical React lifecycle and TypeScript errors in the orbital map and map abstraction layers.

Technical Details

• Microservice Additions: sovereign-gdelt-pulse (Python ingestion) and corresponding FastAPI routers.
• Protocol Updates: Multi-INT HUD now supports GDELT-specific metadata (Goldstein Scale, Average Tone).
• Tooling: Standardized pnpm usage and component-specific verification rules established in AGENTS.md.

Upgrade Instructions

1. Pull the latest changes:

   git pull origin main

2. Rebuild Ingestion Services:

   docker compose up -d --build sovereign-gdelt-pulse sovereign-backend sovereign-frontend

3. Verify Documentation:
   Review Documentation/pollers/GEODENT.md for data pipe verification steps.

Release - v0.45.0 - Ethereal Pulse

This release introduces major architectural consolidations and deep radio intelligence capabilities. Key highlights include the rollout of the JS8Call radio service, unification of the Space domain suite, and a streamlined core codebase with the removal of legacy MCP infrastructure.

Key Features

• JS8Call Tactical Integration: A new full-stack radio service that bridges HF JS8Call traffic directly into the HUD. Features include GhostNet preset synchronization, automated KiwiSDR audio ingestion, and a unified terminal interface.
• Unified Space Pulse: The orbital tracking pipeline has been expanded into a complete Space Domain intelligence service. It now integrates SatNOGS ground station observations and real-time NOAA Space Weather (Aurora/Kp-index) data.
• Documentation Suite v2: Every core guide has been updated to reflect the new service architecture. Includes deep-dive documentation for Space and JS8Call pollers.
• Codebase Sanitization: Successfully decommissioned baked-in MCP support and transitioned to more flexible, agent-driven verification and semantic analysis workflows.

Technical Details

• Service Migration: sovereign-orbital-pulse has been officially renamed to sovereign-space-pulse.
• Dependency Management: Standardized the frontend on pnpm and optimized container build contexts to reduce image sizes.
• Verification Gate: Integrated component-targeting lint/test logic into AGENTS.md and .cursorrules to accelerate the inner-loop development cycle.

Upgrade Instructions

1. Pull and Prune:

   git pull origin main
   docker compose down --remove-orphans

2. Rebuild Suite:

   docker compose build --pull

3. Deploy:

   docker compose up -d

Note: Ensure your .env is updated with the new SPACE_TLE_FETCH_HOUR variable if you were overriding the orbital default.

Release - v0.44.0 - Orbital Fusion & Async Modernization

High-Level Summary

This major update significantly enhances the platform's space domain situational awareness and infrastructure polling efficiency. By integrating the SatNOGS network and introducing a real-time Pass Geometry HUD, operators now have deep visibility into satellite transmitter statuses and upcoming overpass windows. Simultaneously, the backend ingestion architecture has been modernized for massive concurrency, ensuring the platform scales gracefully as new data sources are fused into the tactical picture.

Key Features

• SatNOGS Deep Integration: Live transmitter catalog and ground-station observation cross-referencing for spectrum verification.
• Floating Pass Geometry HUD: Interactive polar plot providing real-time AOS/TCA/Next-Pass metadata for orbital objects.
• Sovereign Glass UI Polish: Improved visual balance with a centered Space Weather monitor and themed orbital widgets.
• Async InfraPoller: 100% async rewrite of infrastructure ingestion, offloading blocking I/O to thread pools for maximum performance.
• Unified SpacePulse Service: Consolidated orbital, weather, and SatNOGS pollers into a single, high-efficiency container.

Technical Details

• Backend: Migrated from requests to httpx and added redis.asyncio support.
• Frontend: Extracted SatelliteSpectrumVerification component and implemented PassGeometryWidget with Deck.gl v9 alignment.
• Schema: Added satnogs_transmitters and satnogs_observations tables to the primary TimescaleDB instance.

Upgrade Instructions

To deploy the new version, pull the latest changes and rebuild the consolidated space service:

docker compose pull
docker compose up -d --build sovereign-space-pulse sovereign-backend-api sovereign-infra-poller