Initial public release

docs/KNOWN_LIMITATIONS.md

@@ -0,0 +1,152 @@
+# GeoIntel v1.0.0 Known Limitations
+
+## Release position
+
+These limitations are explicit, bounded and non-deceptive. None is a hidden
+CRITICAL or HIGH release defect. Coverage and capability responses remain the
+runtime source of truth.
+
+- The access gate intentionally supports one environment-configured operator
+  account. There is no registration, password-recovery email, organisation
+  management or multi-user database. Optional guest access is a short-lived,
+  read-only, demo-project-scoped role; it is not tenant isolation and must be
+  used only on a dedicated demo instance without private data. Operator
+  password rotation remains a configuration action followed by a restart.
+
+## Source coverage
+
+- National administrative land and maritime scope is operational from
+  persisted NGI/RBINS editions. Detailed themes are federated by jurisdiction;
+  an operational Flemish source does not imply equivalent Walloon or Brussels
+  coverage.
+- Land cover remains source-correct by jurisdiction: WALOUS 2018/2020/2023
+  covers Wallonia, Flemish products cover Flanders and UrbIS Land Cover covers
+  Brussels. GeoIntel does not relabel WALOUS as a national source or silently
+  merge incompatible regional legends.
+- Buildings, population, terrain, imagery, nature, agriculture, soil and flood
+  themes may report `partial`, `not_configured` or `unsupported` outside the
+  materialized source partitions. The UI and exports retain that state.
+- Belgian North Sea planning/reporting boundaries are materialized. Bounded
+  strict-TLS MDK WCS acquisition is implemented but stays disabled until the
+  operator enables `MDK_BATHYMETRY_ACQUISITION_ENABLED` with a coverage id that
+  the live readiness probe advertises. Until then the theme reports
+  `not_configured`; VHA profile observations are not presented as a seabed
+  model or water volume.
+- Official endpoints can be temporarily unavailable. Bounded acquisition fails
+  closed and never substitutes fixture or fabricated production data.
+
+## Selection semantics
+
+- Coverage resolution currently accepts an EPSG:4326 rectangle. A rectangle
+  around an irregular municipality or region can include land across a border
+  or adjacent sea, so `outside_supported_scope` can be true even when the
+  underlying named Area itself is wholly valid.
+- Cross-region and land/sea selections stay split by legal/source zone.
+  Semantically incompatible metrics are not merged.
+- Raster analysis is cell-based. A selection smaller than one source cell is
+  answered over the cells it touches, so the analysed area is larger than the
+  drawn area; the response says so rather than returning zeros. Sub-cell
+  precision is not available from a raster source.
+- The object count in a vector selection counts whole features that touch the
+  selection, while area and length metrics clip to it. The response reports how
+  many features the edge cuts; it does not attempt a fractional object count.
+- Flood-hazard percentages are shares of the modelled area. Where the VMM model
+  does not cover the selection, that is reported as missing coverage and never
+  as an absence of risk.
+- Change detection compares whole objects and does not clip them to the
+  selection, so a footprint crossing the selection edge is compared in full.
+  That is deliberate: clipping one snapshot and not the other would report the
+  selection edge itself as a change. The count of such objects is reported.
+- The change-detection GeoJSON is capped by `preview_limit` (changes first).
+  The counts always describe the whole selection; the map does not.
+- An export states its own completeness in `geointel_provenance`. A capped
+  export is still a valid, usable file — it simply no longer implies it holds
+  everything the selection contains.
+- Bounded acquisition refuses any private, loopback or link-local destination,
+  resolving the host first so a DNS name cannot hide one. Two redirect policies
+  apply: the paged OGC feature readers refuse to follow a redirect at all,
+  because a page URL they built themselves should be answered by that URL; the
+  other readers allow a redirect within the configured origin, since providers
+  do version their endpoints. A refused redirect is never requested. An official endpoint
+  that legitimately moves to a new host therefore fails closed until the
+  operator updates the configured URL, which is the intended trade: bytes from
+  an unexpected host must never be persisted under an official provenance.
+- A paged reader stops when the provider stops making progress: a repeated page
+  URL, a repeated page body, or a record already collected all fail the
+  acquisition, and every reader has a page budget. An ArcGIS layer that lacks
+  `supportsPagination` accepts `resultOffset` and ignores it, which otherwise
+  yields a dataset holding several copies of page one while matching the
+  announced record count exactly. Failing is deliberate: a provider that cannot
+  page is a provider whose count proves nothing, so its data cannot carry an
+  official provenance. A duplicate record arriving across two genuinely
+  different pages is kept once instead, since a cursor over a changing table
+  can produce that legitimately.
+
+- The operator profiles in Detection Lab publish figures from historical
+  evaluations, and each names the measurement it came from. Their background
+  numbers are not comparable across profiles: the two showing zero were checked
+  against a strict pure-empty gate of three samples, while the conservative
+  profile's 55 comes from a nine-sample hard-negative matrix that also recorded
+  198 background detections in total. None of the three has an independent
+  hold-out.
+
+## Historical analysis
+
+- Historical comparison requires compatible source editions, units, coverage
+  and observation periods. Sources without a governed series correctly return
+  no comparable time series.
+- The RC10 storage audit reports 224 unavailable historical manifest
+  intermediates from prior operator runs. There are zero missing current
+  database artifact references; the historical paths remain visible as
+  provenance warnings and are protected from cleanup inference.
+
+## AI
+
+- The configured local YOLO model is opt-in, building-focused and bounded by
+  its documented operator evidence. It is not claimed to be an optimally
+  trained general model for all Belgian objects or themes. The capability API
+  exposes this as `nationally_validated=false`, `validated_regions` and an
+  explicit validation scope; operator review remains required.
+- PyTorch and Ultralytics are present only in the AI image. No model weights
+  auto-download. A missing local model reports unavailable.
+- Local YOLO-seg and SAM segmentation are implemented through the ultralytics
+  interface but stay `not_configured` until the operator points
+  `YOLO_SEG_MODEL_PATH`/`SAM_MODEL_PATH` to existing local weights and enables
+  them explicitly. GeoIntel never downloads segmentation weights automatically;
+  fixture segmentation remains explicit-only.
+- The training gate and the workbench measure different things, deliberately.
+  `scripts/evaluate_belgium_building_candidate.py` scores the model on frozen
+  post-processing over its protected test set; the workbench scores the whole
+  production pipeline, which additionally clips to the persisted inference
+  coverage and drops boxes truncated by an interior tile edge. A promoted
+  candidate will therefore not reproduce its gate F1 exactly in the workbench.
+  What must match is the post-processing: `YOLO_CONTAINMENT_NMS_THRESHOLD` and
+  `YOLO_DUPLICATE_IOU_THRESHOLD` are recorded with every run, and two runs that
+  used different values are reported as not comparable.
+- Detection QA reports both a strict footprint IoU and an envelope diagnostic.
+  For an axis-aligned box detector the strict figure has a ceiling below 1 on
+  rotated or non-rectangular buildings; the response states which geometry mode
+  applies rather than silently attributing that gap to detection quality.
+- Segmentation inference still predicts one tile per call. Batching is
+  implemented for detection only, because the SAM adapter is prompt-driven and
+  does not share the detector's batch semantics.
+- Tile-edge truncated boxes are dropped in favour of the overlapping
+  neighbour's complete view. On a manifest generated with `overlap=0` there is
+  no such neighbour, so an object on a seam is lost rather than duplicated.
+  Generate tiles with an overlap larger than the biggest expected object.
+
+## Operations
+
+- Detection and segmentation runs can be queued through
+  `POST /detection/run-async` and executed by the in-process analysis worker, so
+  tiled GPU inference no longer blocks an HTTP request. This is a job table in
+  PostgreSQL polled by the API process, not a distributed durable queue: there
+  is no cross-host distribution and no automatic retry. The synchronous
+  `POST /detection/run` remains available for small runs. Interrupted work is
+  marked failed on restart and must be retried explicitly.
+- Other long GIS work still uses the synchronous job abstraction.
+- GeoIntel remains a controlled single-operator product. The optional guest
+  demo adds bounded presentation access only; multi-user authorization and
+  tenant isolation remain outside the product scope.
+- Cleanup remains manual, dry-run-first and confirmation-gated. No automatic
+  retention schedule is installed.