[Medformatik]

What changed and why

The first two of #303's three parts. The third, the scheduled refresh, comes in a separate PR because it needs a new ops-agent operation for data-manager.

OSM extract age in the admin panel. The admin panel only showed when the PBF was downloaded, which says nothing about how current the data is. A mirror can serve a weeks-old file today. The extract's own header has the real time (osmosis_replication_timestamp) and the diff feed that continues it (osmosis_replication_base_url). Geofabrik and the planet dumps set both.

• Reading the header: data-manager reads both from the PBF's first blob with a small parser, so it doesn't need to run osmium. It records them on the osm-pbf dataset when it downloads, and once at startup for a PBF that was downloaded earlier.
• Admin route: GET /api/admin/services/data adds osmExtract { timestamp, replicationUrl? }. It only uses the dataset whose file name and size match what the ops-agent inventory found, so a record of an older or different file is never shown. If data-manager can't be reached, the field is left out. The ops-agent contract is unchanged.
• OSM card on Data workflows: shows "Data as of" with the time and its age (for example "3 days ago"). Past 30 days it adds an "Older than 30 days" flag. It also shows the extract's update feed, labelled as the value for NOMINATIM_REPLICATION_URL.

Nominatim replication is now configurable. The manifest hard-coded the planet feed and set no UPDATE_MODE. The mediagis 5.3 image defaults that mode to none, so Nominatim never applied diffs and search stayed at its import date.

• New settings: NOMINATIM_REPLICATION_URL, NOMINATIM_UPDATE_MODE, NOMINATIM_REPLICATION_UPDATE_INTERVAL and NOMINATIM_REPLICATION_RECHECK_INTERVAL.
• The defaults are unchanged (planet feed, mode none, 86400 s and 900 s), so existing installs behave exactly as before.
• .env.example, configuration.md and preparing-data.md explain that a regional import must follow its own Geofabrik feed. Otherwise the planet diffs pull in changes from everywhere, the same rule OVERPASS_DIFF_URL already documents.

Related work

Part of #303. Still to do: an optional data-manager schedule that runs the checksummed PBF download, then rebuilds and restarts the consumers. That needs a typed ops-agent operation data-manager may call; today all lifecycle and build operations are API-only.

Verification

• npx vitest run services/data-manager/__tests__ apps/api/src/services/osm-extract.test.ts apps/api/src/routes/__tests__/admin-services-sdk.test.ts apps/web/src/components/admin/services scripts/ops-authority-inventory.test.ts packages/core/src/api/contracts/service-admin.test.ts packages/core/src/services: everything passes except four tests in packages/core/src/services/__tests__ (checkout-layout, deployment-user, traefik-files). Those four fail identically on main in this environment, which runs as root.
• Parser tests: use two fixtures written by libosmium (pyosmium) from the existing traffic-engine fixture, one zlib-compressed and one raw, each with a Geofabrik-style replication header. They also cover a PBF without replication data, a file that isn't a PBF, a truncated file, and a non-https feed being dropped.
• Download and admin tests:
  • the download records the header fields
  • the backfill fills only PBFs that are missing them
  • the admin lookup ignores records for a different file or size
  • the card shows the age, the 30-day flag and the "unknown" state
• Type checks and generated files:
  • tsc --noEmit passes in packages/core, services/data-manager, apps/api and apps/web.
  • check-openapi, check-api-sdk, check-data-manager-openapi, check-data-manager-sdk and check-ops-authority pass.
  • Both OpenAPI documents were regenerated, and their diffs contain only the new fields.
• Not done:
  • I couldn't download a real Geofabrik extract here (the proxy blocks it), so the parser hasn't been run against one.
  • The Nominatim behaviour comes from reading the mediagis 5.3 image's start.sh, init.sh and config.sh, not from a running instance.
  • No browser check of the admin card.

Release and upgrade impact

@openmapx/extension-cli bundles the data-manager dataset schema, which gains two optional fields, so there's a patch Changeset. No operator action: the new Nominatim settings default to the old fixed values. To keep search current on a regional install, set NOMINATIM_REPLICATION_URL to the extract's feed (shown on the OSM card) and NOMINATIM_UPDATE_MODE=continuous, then recreate Nominatim.