# Map Domain Ontology

Package: `catalog/domain-packages/map`

Status: first provider-neutral ontology slice for NDC Module Studio Map Page.

## Purpose

The package names stable spatial meanings already evidenced by the ENGINE MMAP workflow without making the current Cesium implementation canonical.

The Map Page, its visual components and renderer adapters belong to NDC Module Studio. ENGINE and NDC sources produce normalized domain data and commands through the Future Interface binding boundary. Platform services own access, provider credentials, proxy/cache and deployment concerns.

## Evidence boundary

The donor inspection covered the working `MMAP` workflow and its node of type `cesium`, plus Gelios, RZD/Yandex Rasp, Rail Inspector, city target, selection and grid layers.

The old `MoscowMapNode` is not a canonical donor. Runtime snapshots, provider tokens and full geometry datasets are evidence only and are not copied into Ontology Core.

## Canonical layers

```text
NDC domain source
  -> moving objects, places, zones, routes, tracks, stations and events
  -> Future Interface binding
  -> Map View / Map Page slots
  -> shared pin, label, selection, style and visibility contracts
  -> replaceable renderer adapter
  -> provider capabilities
```

Cesium is one possible renderer adapter. A future Cesium version or another provider can replace it without changing Map View, application manifests or domain subject identifiers.

## Interface semantic ownership

Interface entities belong in this shared Ontology Core, not in a parallel Studio-specific ontology:

| Layer | Owns |
| --- | --- |
| Ontology Core | Canonical meanings and relations: future.interface_view, future.interface_widget, future.interface_binding, map.view, map.moving_object, map.pin, map.label, map.visibility_rule and map.renderer_adapter. |
| NDC Module Studio | React implementation, saved visual profiles, page templates, application manifests and the concrete layout chosen by an application owner. |
| Engine / NDC workflow | Source integration, normalization and emission of stable subject IDs, current positions, statuses and approved display fields. |
| Platform Map Gateway | Provider tokens, cache, proxying and the renderer runtime boundary. |

Ontology Core never becomes a UI database. It does not store a user's live page layout, camera snapshot, provider token, renderer object ID, telemetry feed or tile cache.

## Pin presentation contract v0.1

map.pin is a reusable interface semantic, not a Cesium entity. The initial canonical variant is elevated-spike, based on the accepted Gelios donor:

~~~text
ground anchor
  -> coloured stem at a semantic height
  -> outlined point/head
  -> shared map.label with explicit anchor and offset
  -> separate pin and label visibility thresholds
~~~

Studio resolves a selected map.pin style profile into this contract. The renderer adapter decides whether its concrete implementation is a polyline and point, a mesh, a sprite or another primitive. A source payload only identifies the stable moving subject, its position/status and approved label fields; it never specifies renderer primitives or provider-specific IDs.

## First acceptance slice

The first fixture-backed Map Page must cover:

- viewport and saved view;
- base/building layer capability states;
- multi-level grid using both local 3D and distant graticule modes;
- place targets with pulse and scale-by-distance;
- moving transport objects using shared pins and labels;
- metro, railway station, stop and terminal variants;
- railway route and track geometry;
- polygon/multipolygon zones with level-dependent style;
- selection driving Inspector or a quick card;
- loading, empty, stale, error and offline states.

## Known donor debt

- Viewer lifecycle, map provider setup, cache, grid and layer orchestration are concentrated in one large node.
- Labels are independently implemented by multiple source-specific layers.
- Large geozone sets are rendered as many individual polygon/polyline entities.
- Railway source handling, geometry LOD and renderer logic are only partially separated.
- Existing Grid/AIS rendering relies on a proxy canvas because moving a live WebGL canvas is unstable.

These constraints guide acceptance tests but do not become public Map Page contracts.
