Phantom Tide Maritime and Airspace Intelligence

Operator Guide

  • Operational reading surface
  • Public instance
  • James Sawyer / JS Labs
  • v1.79.0

This public deployment exposes a bounded starter surface. Read it as an operational reference: confirm access level, freshness, source family, and whether a result is directly observed or replay-derived before drawing conclusions.

One route is public by design: /api/public/aircraft/restricted-airspace-crossings. It is a bounded teaser and ingestion feed for replay-derived airspace-crossing candidates. The richer analyst ledger remains tier-limited inside Phantom Tide intel tables.

The rest of this guide explains how to interpret that split cleanly: what is public, what is capped, what is current, what is inferred, and which route or source family produced the visible state.

  • Public route Restricted-airspace crossing feed, bounded and pollable.
  • Analyst lane Replay-oriented crossing ledger inside intel tables, tier-limited on public starter access.
  • Freshness basis Archived movement history plus reference geometry used for contextual matching.
  • Trust boundary Candidate crossings are derived context, not a live alert or final determination.

Public Route Reference

  • Route GET /api/public/aircraft/restricted-airspace-crossings
  • Parameters hours, limit, include_meta, sample_after, sample_before
  • Access Open. No browser-session upgrade or API key is required for this route.
  • Use case Third-party integration, bounded public context, and teaser visibility when the in-product analyst ledger is tier-limited.

Public Restricted-Airspace Feed

This is the public route that integrators and reviewers can call directly. It exposes candidate airspace crossings from replayed movement history and keeps the trust boundary explicit: public, bounded, replay-derived, and not a live alerting surface.

Route Access Primary output Trust note
/api/public/aircraft/restricted-airspace-crossings Open public route Bounded candidate crossing rows plus optional freshness and contract metadata. Replay-derived context feed. Not a live alarm surface.

Query parameters

Parameter Meaning
hours Bound the replay window. Minimum effective window is one hour.
limit Cap the returned rows for predictable polling and integration.
include_meta Include freshness, reference context, quality, and contract blocks.
sample_after / sample_before Use watermark polling on sample_at without refetching old rows.

Representative call

curl --max-time 30 --get \
  'https://phantom.labs.jamessawyer.co.uk/api/public/aircraft/restricted-airspace-crossings' \
  --data-urlencode 'hours=1' \
  --data-urlencode 'limit=5' \
  --data-urlencode 'include_meta=true'

Representative response shape

{
  "hours": 1,
  "aircraft_count": 3,
  "crossing_count": 2,
  "latest_when": "2026-05-20T00:20:43",
  "poll_after": "2026-05-20T00:20:43",
  "crossings": [
    {
      "event_id": "airspace-crossing:sample-track:reference-zone:exited:2026-05-20T00:20:43",
      "when": "2026-05-20T00:20:43",
      "who": { "icao24": "sample01", "callsign": "TRACK01" },
      "what": {
        "transition": "exited",
        "airspace": {
          "feature_id": "reference-zone:sample",
          "name": "Reference zone",
          "restriction_label": "Restricted area"
        }
      },
      "where": { "lat": 38.016, "lon": -123.144 }
    }
  ],
  "partial": false,
  "empty_reason": null,
  "quality": { "status": "current", "reference_available": true },
  "contract": {
    "mode": "public_candidate_restricted_airspace_crossing_feed",
    "alert_surface": false,
    "pollable": true
  }
}

Operational Model

The interface is intentionally compact. It should tell you four things immediately: what state the system is in, what changed recently, which data families are fresh or stale, and whether the current view is showing direct evidence or a ranked inference surface.

Primary operational state at a glance

  • Header state tells you whether the browser surface is current, paused, or waiting for user action.
  • Source state tells you whether upstream collection is live, degraded, stale, or tier-limited.
  • Absence is only meaningful after state and freshness are confirmed.

What changed recently

  • Recent changes belong in visible lanes: changed alerts, changed cells, new contributors, and updated time bars.
  • Nothing should imply a global redraw if only one visible lane changed.
  • Motion should explain state change, not add spectacle.

Example reading order

Header and selected signal
Browser sync current OpenSky degraded Convergence inferred

Read this first

Mode, refresh state, and access tier define what the page can claim.

Open the selected signal and inspect the direct source rows before trusting the map icon or score.

Then decide

If evidence is direct and fresh, continue to history or area analysis.

If evidence is partial or degraded, narrow the area and corroborate with another family before reporting.

State, Freshness, Confidence

State colours are semantic, not decorative. A neutral page can still carry a strong operational hierarchy if the labels are explicit and the user can trace them to raw source conditions.

State Meaning Operator implication
Live Latest ingest succeeded and the source is updating on its expected cadence. Treat absence as potentially meaningful only after confirming zoom, scope, and coverage.
Degraded Source answered, but completeness, subtype fidelity, or quality fell. Keep using it for context, not for clean negative assertions.
Stale Old or cached data remains visible for continuity. Useful for orientation. Unsafe for time-sensitive conclusions.
Tier-limited Feature exists but the current access path is intentionally capped. Do not confuse intentional suppression with lack of signal.

Confidence display rule

Confidence should never be shown as a floating number without a basis. Confidence is a statement about source agreement, freshness, and directness of evidence.

Suggested UI labels: Observed Corroborated Estimated Weakly supported

Freshness display rule

Freshness should be visible in both relative and absolute time. Showing only “5m ago” is not enough for analysts working across time zones and archived sessions.

  • Show last successful update time.
  • Show cadence family.
  • Show missing-source count when a composite layer depends on multiple feeds.

Evidence And Lineage

Every alert, zone, and summary should expose where it came from. Users need to distinguish direct observation, derived context, replay or archive-backed material, and plain inference without opening the code.

Lineage label What it means How it should appear
Direct observation Source row or primary detection from a feed such as AIS, OpenSky, VIIRS, NOTAM, or advisory text. Visible source family badge, timestamp, and raw-access link.
Derived context Geometry, proximity, recurrence, clustering, or replay-derived candidate events built from direct source material. Explicit “derived” label plus the underlying source list.
Estimated field Approximation, fallback classification, or incomplete identity enrichment. Muted label, explanation tooltip, and lower confidence treatment.
Reference layer Static or slowly changing contextual layer such as restricted airspace or infrastructure reference data. Show snapshot age and missing-artifact status where relevant.

Example detail panel evidence block

Tracked aircraft signal
Corroborated OpenSky current Reference layer 6h old

Observed

Source OpenSky state vector, sampled 2026-05-20 00:03 UTC
Identity ICAO24 observed directly, callsign observed directly, registration enriched from local registry
Raw access Open raw row, view history points, inspect recent watchlist matches

Derived

Crossing Restricted-airspace candidate crossing is replay-derived from track points and FAA polygon geometry.
Confidence Medium because geometry and timing align, but intent is not directly observable.
Warning Do not describe this as an incursion verdict without independent corroboration.

Critical Workflows

The interface should support questions, not sightseeing. Each major workflow should collapse the analyst’s path from map signal to plain language answer with minimal mode switching.

Tracked aircraft workflow

  • Watch the banner or intel rows for a tracked-aircraft hit.
  • Open the detail panel before reacting to icon shape or colour.
  • Verify callsign, registration, timing, and geometry separately.
  • Use track history when a single state vector is not enough.

Convergence workflow

  • Use convergence to rank where attention should go first.
  • Open the zone and inspect contributor families and time change.
  • Treat the score as triage only until evidence lineage is opened.
  • Drill in before dismissing lower-priority cells at world zoom.

Proximity and area analysis

  • Right-click any point to open a radius query.
  • Use Proximity Query when distance and neighboring context matter.
  • Use Area Intelligence Report when you need a deterministic sitrep tied to a fixed circle.
  • Verify the highlighted area before copying any result downstream.

Freshness-first workflow

  • Check browser refresh state and upstream source state separately.
  • Fast browser sync does not guarantee fast upstream collection.
  • Composite layers should expose missing-source counts and stale contributors.
  • Report the freshest trustworthy path, not the most dramatic signal.

Component Hierarchy

The page and the product should share the same visual logic: restrained hierarchy, compact density, semantic colour, and tables wherever comparison matters more than decoration.

Component Purpose Display rule
Header state bar Primary operational truth for mode, sync state, access, and time basis. Always visible. No decorative motion.
Intel table Recent change surface where comparison, sorting, and keyboard navigation matter. Prefer rows over cards. Make time, source family, and confidence scannable.
Detail panel Evidence inspection unit for selected signal. Separate observed, inferred, and reference context blocks.
Map Spatial triage and area framing. Only analytical geometry belongs here. No decorative overlays.
Area report Plain-language output for a fixed radius and time frame. Must inherit source state and freshness qualifiers from contributing layers.

Source Families And Cadence

Source family matters as much as freshness. Some feeds are continuous, some hourly, some analyst-reviewed, and some reference-only. Users should be able to see both the family and the cadence without opening a settings panel.

Family Examples Cadence logic
Transport broadcast AIS, OpenSky aircraft state vectors, entity-feed context Frequent. Best for motion and absence checks, but still subject to source outages and spoofing.
Advisory and warning NOTAM, maritime advisories, navigation warnings, SIGMET Periodic. Useful for declared restrictions, hazards, and official context windows.
Environmental and sensor NDBC, VIIRS, seismic, GPS disruption, space weather Mixed cadence. Often strongest when used to challenge transport claims.
Reference context Restricted airspace, infrastructure layers, static overlays Slow-moving. Must expose snapshot age and missing-artifact status.

Interaction Rules

Progressive disclosure should reduce clutter without hiding the truth. The interface can be calm and dense at the same time if every reveal is in service of a real investigative decision.

Good disclosure

  • Open raw rows only when the operator asks.
  • Hide low-priority convergence cells until zoom makes them legible.
  • Pause live-mode redraw while the user inspects detail or types.
  • Show exact reasons for empty or partial views.

Bad disclosure

  • Hiding stale state behind “success” phrasing.
  • Using colour to imply severity without source basis.
  • Animating updates that do not correspond to actual state change.
  • Collapsing observed and inferred data into one unlabelled block.

Keyboard and reversibility

Fast operators need reversible actions more than hidden power features. Keep `?`, `Escape`, time-basis toggle, intel focus, row navigation, and map-focus shortcuts stable so trust is preserved across modes and sessions.