@nspot/geo-engine 0.1.0

package/sql/001_init.sql

@@ -0,0 +1,188 @@
+-- ============================================================================
+-- geo-engine — core schema
+--
+-- Design:
+--   * Geometry is the single source of truth. A location "belongs" to a region
+--     iff the region polygon covers the location point. Nothing is stored about
+--     that relationship at write time by the application.
+--   * Regions of any type (admin / cultural / natural / custom) may overlap
+--     freely; a point can be in many regions at once.
+-- ============================================================================
+
+CREATE EXTENSION IF NOT EXISTS postgis;
+
+DO $$ BEGIN
+  CREATE TYPE region_type AS ENUM ('admin', 'cultural', 'natural', 'custom');
+EXCEPTION WHEN duplicate_object THEN NULL; END $$;
+
+-- ----------------------------------------------------------------------------
+-- countries
+-- ----------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS countries (
+  id          serial PRIMARY KEY,
+  code        char(2) NOT NULL UNIQUE,          -- ISO 3166-1 alpha-2, e.g. 'RO'
+  name        text NOT NULL,
+  geom        geometry(MultiPolygon, 4326),     -- optional; derived from admin regions if missing
+  created_at  timestamptz NOT NULL DEFAULT now(),
+  updated_at  timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS countries_geom_gix ON countries USING GIST (geom);
+
+-- ----------------------------------------------------------------------------
+-- regions
+-- ----------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS regions (
+  id          serial PRIMARY KEY,
+  country_id  int NOT NULL REFERENCES countries(id) ON DELETE CASCADE,
+  parent_id   int REFERENCES regions(id) ON DELETE SET NULL,
+  type        region_type NOT NULL DEFAULT 'custom',
+  level       smallint,                          -- admin level (1 = județ); NULL for non-admin
+  slug        text NOT NULL,                     -- unique per country, URL-safe
+  name        text NOT NULL,
+  code        text,                              -- e.g. ISO 3166-2 'RO-CJ'
+  tags        text[] NOT NULL DEFAULT '{}',
+  properties  jsonb NOT NULL DEFAULT '{}',
+  geom        geometry(MultiPolygon, 4326) NOT NULL,
+  created_at  timestamptz NOT NULL DEFAULT now(),
+  updated_at  timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (country_id, slug)
+);
+CREATE INDEX IF NOT EXISTS regions_geom_gix     ON regions USING GIST (geom);
+CREATE INDEX IF NOT EXISTS regions_country_type ON regions (country_id, type);
+CREATE INDEX IF NOT EXISTS regions_parent_idx   ON regions (parent_id);
+CREATE INDEX IF NOT EXISTS regions_tags_gin     ON regions USING GIN (tags);
+
+-- ----------------------------------------------------------------------------
+-- helpers
+-- ----------------------------------------------------------------------------
+
+-- Normalise any GeoJSON area geometry (Polygon / MultiPolygon, possibly invalid,
+-- possibly wrapped in a Feature) into a valid MultiPolygon in EPSG:4326.
+CREATE OR REPLACE FUNCTION geom_from_geojson_area(gj jsonb)
+RETURNS geometry(MultiPolygon, 4326)
+LANGUAGE plpgsql IMMUTABLE STRICT AS $$
+DECLARE
+  g geometry;
+BEGIN
+  IF gj->>'type' = 'Feature' THEN
+    gj := gj->'geometry';
+  END IF;
+  IF gj IS NULL OR gj->>'type' NOT IN ('Polygon', 'MultiPolygon', 'GeometryCollection') THEN
+    RAISE EXCEPTION 'Expected a Polygon or MultiPolygon GeoJSON geometry, got %', coalesce(gj->>'type', 'null')
+      USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+  g := ST_SetSRID(ST_GeomFromGeoJSON(gj::text), 4326);
+  g := ST_CollectionExtract(ST_MakeValid(g), 3);   -- keep only polygonal parts
+  IF g IS NULL OR ST_IsEmpty(g) THEN
+    RAISE EXCEPTION 'Geometry has no polygonal area' USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+  RETURN ST_Multi(g)::geometry(MultiPolygon, 4326);
+END $$;
+
+CREATE OR REPLACE FUNCTION set_updated_at() RETURNS trigger
+LANGUAGE plpgsql AS $$
+BEGIN
+  NEW.updated_at := now();
+  RETURN NEW;
+END $$;
+
+-- ----------------------------------------------------------------------------
+-- triggers
+-- ----------------------------------------------------------------------------
+
+DROP TRIGGER IF EXISTS regions_updated_at_trg ON regions;
+CREATE TRIGGER regions_updated_at_trg
+  BEFORE UPDATE ON regions
+  FOR EACH ROW EXECUTE FUNCTION set_updated_at();
+
+DROP TRIGGER IF EXISTS countries_updated_at_trg ON countries;
+CREATE TRIGGER countries_updated_at_trg
+  BEFORE UPDATE ON countries
+  FOR EACH ROW EXECUTE FUNCTION set_updated_at();
+
+-- ----------------------------------------------------------------------------
+-- write helpers used by the API, the seed and the import CLI
+-- ----------------------------------------------------------------------------
+
+CREATE OR REPLACE FUNCTION upsert_country(p_code text, p_name text, p_geojson jsonb)
+RETURNS countries
+LANGUAGE plpgsql AS $$
+DECLARE
+  c countries;
+BEGIN
+  INSERT INTO countries (code, name, geom)
+  VALUES (upper(p_code), p_name, CASE WHEN p_geojson IS NULL THEN NULL ELSE geom_from_geojson_area(p_geojson) END)
+  ON CONFLICT (code) DO UPDATE
+    SET name = EXCLUDED.name,
+        geom = coalesce(EXCLUDED.geom, countries.geom)
+  RETURNING * INTO c;
+  RETURN c;
+END $$;
+
+CREATE OR REPLACE FUNCTION upsert_region(
+  p_country_code text,
+  p_slug         text,
+  p_name         text,
+  p_type         region_type,
+  p_level        int,
+  p_parent_id    int,
+  p_code         text,
+  p_tags         text[],
+  p_properties   jsonb,
+  p_geojson      jsonb,
+  p_upsert       boolean DEFAULT true      -- false: fail with unique_violation if the slug exists
+) RETURNS regions
+LANGUAGE plpgsql AS $$
+DECLARE
+  r   regions;
+  cid int;
+BEGIN
+  SELECT id INTO cid FROM countries WHERE code = upper(p_country_code);
+  IF cid IS NULL THEN
+    RAISE EXCEPTION 'Unknown country code %', p_country_code USING ERRCODE = 'foreign_key_violation';
+  END IF;
+  IF NOT p_upsert AND EXISTS (SELECT 1 FROM regions WHERE country_id = cid AND slug = p_slug) THEN
+    RAISE EXCEPTION 'A region with slug "%" already exists in %', p_slug, upper(p_country_code)
+      USING ERRCODE = 'unique_violation';
+  END IF;
+
+  INSERT INTO regions (country_id, slug, name, type, level, parent_id, code, tags, properties, geom)
+  VALUES (cid, p_slug, p_name, p_type, p_level, p_parent_id, p_code,
+          coalesce(p_tags, '{}'), coalesce(p_properties, '{}'), geom_from_geojson_area(p_geojson))
+  ON CONFLICT (country_id, slug) DO UPDATE
+    SET name       = EXCLUDED.name,
+        type       = EXCLUDED.type,
+        level      = EXCLUDED.level,
+        parent_id  = EXCLUDED.parent_id,
+        code       = EXCLUDED.code,
+        tags       = EXCLUDED.tags,
+        properties = EXCLUDED.properties,
+        geom       = EXCLUDED.geom
+  RETURNING * INTO r;
+  RETURN r;
+END $$;
+
+-- If a country has no outline, build one as the union of its admin regions.
+CREATE OR REPLACE FUNCTION derive_country_geom(p_code text) RETURNS void
+LANGUAGE plpgsql AS $$
+BEGIN
+  UPDATE countries c
+  SET geom = sub.g
+  FROM (
+    SELECT r.country_id, ST_Multi(ST_UnaryUnion(ST_Collect(r.geom)))::geometry(MultiPolygon,4326) AS g
+    FROM regions r JOIN countries cc ON cc.id = r.country_id
+    WHERE cc.code = upper(p_code) AND r.type = 'admin'
+    GROUP BY r.country_id
+  ) sub
+  WHERE c.id = sub.country_id;
+END $$;
+
+-- Live (uncached) lookup: every region covering an arbitrary point.
+CREATE OR REPLACE FUNCTION regions_at_point(p_lng double precision, p_lat double precision)
+RETURNS SETOF regions
+LANGUAGE sql STABLE AS $$
+  SELECT r.*
+  FROM regions r
+  WHERE ST_Intersects(r.geom, ST_SetSRID(ST_MakePoint(p_lng, p_lat), 4326))
+  ORDER BY r.type, r.level NULLS LAST, r.name;
+$$;

package/sql/002_geojson_null_geometry.sql

@@ -0,0 +1,26 @@
+-- geom_from_geojson_area: a Feature with "geometry": null unwraps to a JSON null
+-- (not SQL NULL), and `NULL NOT IN (...)` is not true, so it slipped past the
+-- type check and failed later with PostGIS' generic "invalid GeoJSON
+-- representation". Check the JSON value's type explicitly instead.
+CREATE OR REPLACE FUNCTION geom_from_geojson_area(gj jsonb)
+RETURNS geometry(MultiPolygon, 4326)
+LANGUAGE plpgsql IMMUTABLE STRICT AS $$
+DECLARE
+  g geometry;
+BEGIN
+  IF gj->>'type' = 'Feature' THEN
+    gj := gj->'geometry';
+  END IF;
+  IF gj IS NULL OR jsonb_typeof(gj) <> 'object'
+     OR coalesce(gj->>'type', '') NOT IN ('Polygon', 'MultiPolygon', 'GeometryCollection') THEN
+    RAISE EXCEPTION 'Expected a Polygon or MultiPolygon GeoJSON geometry, got %',
+      CASE WHEN gj IS NULL OR jsonb_typeof(gj) <> 'object' THEN 'null' ELSE coalesce(gj->>'type', 'null') END
+      USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+  g := ST_SetSRID(ST_GeomFromGeoJSON(gj::text), 4326);
+  g := ST_CollectionExtract(ST_MakeValid(g), 3);   -- keep only polygonal parts
+  IF g IS NULL OR ST_IsEmpty(g) THEN
+    RAISE EXCEPTION 'Geometry has no polygonal area' USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+  RETURN ST_Multi(g)::geometry(MultiPolygon, 4326);
+END $$;

package/sql/003_geo_schema.sql

@@ -0,0 +1,364 @@
+-- ============================================================================
+-- 003 — move the engine into its own schema and generalise memberships
+--
+--   * every table, type and function now lives in schema `geo`, so the engine
+--     can be installed next to a host application's own tables
+--   * membership means ST_Intersects, generalised to any geometry type
+--   * memberships are kept for any *registered source table*. The demo table
+--     (geo.locations) is no longer part of this core set: it is applied
+--     separately by @geo/db from packages/db/sql-demo, after this migration.
+-- ============================================================================
+
+CREATE SCHEMA IF NOT EXISTS geo;
+
+-- ---------------------------------------------------------------- move objects
+ALTER TYPE public.region_type SET SCHEMA geo;
+ALTER TABLE public.countries SET SCHEMA geo;
+ALTER TABLE public.regions SET SCHEMA geo;
+
+DROP TRIGGER IF EXISTS regions_refresh_memberships_trg ON geo.regions;
+DROP TRIGGER IF EXISTS regions_updated_at_trg ON geo.regions;
+DROP TRIGGER IF EXISTS countries_updated_at_trg ON geo.countries;
+
+-- every signature is spelled out so a host function that happens to share a name
+-- but not an argument list is never dropped (region_type has just moved to geo,
+-- so upsert_region's fourth argument is already geo.region_type here)
+DROP FUNCTION IF EXISTS public.set_updated_at();
+DROP FUNCTION IF EXISTS public.upsert_country(text, text, jsonb);
+DROP FUNCTION IF EXISTS public.upsert_region(text, text, text, geo.region_type, int, int, text, text[], jsonb, jsonb, boolean);
+DROP FUNCTION IF EXISTS public.derive_country_geom(text);
+DROP FUNCTION IF EXISTS public.regions_at_point(double precision, double precision);
+DROP FUNCTION IF EXISTS public.geom_from_geojson_area(jsonb);
+
+-- ---------------------------------------------------------------- new tables
+CREATE TABLE geo.sources (
+  id            serial PRIMARY KEY,
+  name          text NOT NULL UNIQUE,
+  table_schema  text NOT NULL,
+  table_name    text NOT NULL,
+  id_column     text NOT NULL,
+  id_type       text NOT NULL,      -- SQL type of the id column, e.g. 'integer', 'uuid'
+  geom_expr     text NOT NULL,      -- expression over a row alias `r` yielding geometry(…, 4326)
+  registered_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (table_schema, table_name)
+);
+
+CREATE TABLE geo.memberships (
+  source_id   int  NOT NULL REFERENCES geo.sources(id) ON DELETE CASCADE,
+  external_id text NOT NULL,
+  region_id   int  NOT NULL REFERENCES geo.regions(id) ON DELETE CASCADE,
+  PRIMARY KEY (source_id, external_id, region_id)
+);
+CREATE INDEX memberships_region_idx ON geo.memberships (region_id);
+
+CREATE OR REPLACE FUNCTION geo.schema_version() RETURNS int
+LANGUAGE sql STABLE AS $$
+  SELECT coalesce(max(split_part(name, '_', 1)::int), 0) FROM geo.schema_migrations;
+$$;
+
+-- ---------------------------------------------------------------- helpers
+CREATE OR REPLACE FUNCTION geo.geom_from_geojson_area(gj jsonb)
+RETURNS geometry(MultiPolygon, 4326)
+LANGUAGE plpgsql IMMUTABLE STRICT AS $$
+DECLARE
+  g geometry;
+BEGIN
+  IF gj->>'type' = 'Feature' THEN
+    gj := gj->'geometry';
+  END IF;
+  IF gj IS NULL OR jsonb_typeof(gj) <> 'object'
+     OR coalesce(gj->>'type', '') NOT IN ('Polygon', 'MultiPolygon', 'GeometryCollection') THEN
+    RAISE EXCEPTION 'Expected a Polygon or MultiPolygon GeoJSON geometry, got %',
+      CASE WHEN gj IS NULL OR jsonb_typeof(gj) <> 'object' THEN 'null' ELSE coalesce(gj->>'type', 'null') END
+      USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+  g := ST_SetSRID(ST_GeomFromGeoJSON(gj::text), 4326);
+  g := ST_CollectionExtract(ST_MakeValid(g), 3);
+  IF g IS NULL OR ST_IsEmpty(g) THEN
+    RAISE EXCEPTION 'Geometry has no polygonal area' USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+  RETURN ST_Multi(g)::geometry(MultiPolygon, 4326);
+END $$;
+
+CREATE OR REPLACE FUNCTION geo.set_updated_at() RETURNS trigger
+LANGUAGE plpgsql AS $$
+BEGIN
+  NEW.updated_at := now();
+  RETURN NEW;
+END $$;
+
+CREATE TRIGGER regions_updated_at_trg
+  BEFORE UPDATE ON geo.regions FOR EACH ROW EXECUTE FUNCTION geo.set_updated_at();
+CREATE TRIGGER countries_updated_at_trg
+  BEFORE UPDATE ON geo.countries FOR EACH ROW EXECUTE FUNCTION geo.set_updated_at();
+
+-- ---------------------------------------------------------------- memberships
+-- Row trigger installed on every registered source table. TG_ARGV[0] is the
+-- geo.sources id. The host's id column and geometry expression are read from
+-- geo.sources and evaluated dynamically against the row.
+CREATE OR REPLACE FUNCTION geo.source_row_changed() RETURNS trigger
+LANGUAGE plpgsql AS $$
+DECLARE
+  s      geo.sources;
+  new_id text;
+  old_id text;
+  new_g  geometry;
+  old_g  geometry;
+  q      text;
+BEGIN
+  IF current_setting('geo.skip_membership_triggers', true) = 'on' THEN
+    RETURN NULL;
+  END IF;
+  SELECT * INTO s FROM geo.sources WHERE id = TG_ARGV[0]::int;
+  IF s.id IS NULL THEN
+    RETURN NULL;   -- source was unregistered; nothing to maintain
+  END IF;
+  q := format('SELECT r.%I::text, (%s)::geometry FROM (SELECT ($1::%I.%I).*) AS r',
+              s.id_column, s.geom_expr, s.table_schema, s.table_name);
+
+  IF TG_OP IN ('UPDATE', 'DELETE') THEN
+    EXECUTE q INTO old_id, old_g USING OLD;
+  END IF;
+  IF TG_OP IN ('INSERT', 'UPDATE') THEN
+    EXECUTE q INTO new_id, new_g USING NEW;
+  END IF;
+
+  IF TG_OP = 'UPDATE' AND new_id = old_id
+     AND ((new_g IS NULL AND old_g IS NULL) OR (new_g IS NOT NULL AND old_g IS NOT NULL AND ST_Equals(new_g, old_g))) THEN
+    RETURN NULL;   -- neither the id nor the geometry changed
+  END IF;
+
+  IF old_id IS NOT NULL THEN
+    DELETE FROM geo.memberships WHERE source_id = s.id AND external_id = old_id;
+  END IF;
+  IF new_id IS NOT NULL THEN
+    IF new_id IS DISTINCT FROM old_id THEN   -- otherwise the DELETE above already removed it
+      DELETE FROM geo.memberships WHERE source_id = s.id AND external_id = new_id;
+    END IF;
+    IF new_g IS NOT NULL THEN
+      INSERT INTO geo.memberships (source_id, external_id, region_id)
+      SELECT s.id, new_id, r.id FROM geo.regions r WHERE ST_Intersects(r.geom, new_g);
+    END IF;
+  END IF;
+  RETURN NULL;
+END $$;
+
+-- A region was inserted or reshaped: recompute its members in every source.
+CREATE OR REPLACE FUNCTION geo.regions_refresh_memberships() RETURNS trigger
+LANGUAGE plpgsql AS $$
+DECLARE
+  s geo.sources;
+BEGIN
+  IF current_setting('geo.skip_membership_triggers', true) = 'on' THEN
+    RETURN NULL;
+  END IF;
+  IF TG_OP = 'UPDATE' AND ST_Equals(NEW.geom, OLD.geom) THEN
+    RETURN NULL;
+  END IF;
+  DELETE FROM geo.memberships WHERE region_id = NEW.id;
+  FOR s IN SELECT * FROM geo.sources LOOP
+    -- a registered table that was dropped or renamed must not break region writes
+    IF to_regclass(format('%I.%I', s.table_schema, s.table_name)) IS NULL THEN
+      RAISE WARNING 'geo: source "%" points at %.% which no longer exists; run geo.unregister_source(%L)',
+        s.name, s.table_schema, s.table_name, s.name;
+      CONTINUE;
+    END IF;
+    EXECUTE format(
+      'INSERT INTO geo.memberships (source_id, external_id, region_id)
+       SELECT %s, r.%I::text, %s FROM %I.%I r WHERE ST_Intersects($1, (%s)::geometry)',
+      s.id, s.id_column, NEW.id, s.table_schema, s.table_name, s.geom_expr)
+      USING NEW.geom;
+  END LOOP;
+  RETURN NULL;
+END $$;
+
+CREATE TRIGGER regions_refresh_memberships_trg
+  AFTER INSERT OR UPDATE OF geom ON geo.regions
+  FOR EACH ROW EXECUTE FUNCTION geo.regions_refresh_memberships();
+
+CREATE OR REPLACE FUNCTION geo.rebuild_memberships(p_source text) RETURNS bigint
+LANGUAGE plpgsql AS $$
+DECLARE
+  s geo.sources;
+  n bigint;
+BEGIN
+  SELECT * INTO s FROM geo.sources WHERE name = p_source;
+  IF s.id IS NULL THEN
+    RAISE EXCEPTION 'Unknown source "%"', p_source USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+  DELETE FROM geo.memberships WHERE source_id = s.id;
+  IF to_regclass(format('%I.%I', s.table_schema, s.table_name)) IS NULL THEN
+    RAISE WARNING 'geo: source "%" points at %.% which no longer exists; run geo.unregister_source(%L)',
+      s.name, s.table_schema, s.table_name, s.name;
+    RETURN 0;   -- the memberships we just dropped could not be valid any more
+  END IF;
+  -- the source row is resolved in a subquery (aliased r there) before joining to
+  -- geo.regions (aliased g): geom_expr may be a bare column such as "geom", which
+  -- would otherwise collide with geo.regions.geom once both aliases are in scope
+  EXECUTE format(
+    'INSERT INTO geo.memberships (source_id, external_id, region_id)
+     SELECT %s, x.rid, g.id
+     FROM (SELECT r.%I::text AS rid, (%s)::geometry AS rgeom FROM %I.%I r) x
+     JOIN geo.regions g ON ST_Intersects(g.geom, x.rgeom)',
+    s.id, s.id_column, s.geom_expr, s.table_schema, s.table_name);
+  GET DIAGNOSTICS n = ROW_COUNT;
+  RETURN n;
+END $$;
+
+CREATE OR REPLACE FUNCTION geo.rebuild_all_memberships() RETURNS bigint
+LANGUAGE plpgsql AS $$
+DECLARE
+  total bigint := 0;
+  s geo.sources;
+BEGIN
+  FOR s IN SELECT * FROM geo.sources ORDER BY id LOOP
+    total := total + geo.rebuild_memberships(s.name);
+  END LOOP;
+  RETURN total;
+END $$;
+
+-- Register a host table. Validates the table, the id column and the geometry
+-- expression (compiled with LIMIT 0), installs the row trigger and builds the
+-- initial memberships.
+CREATE OR REPLACE FUNCTION geo.register_source(
+  p_name text, p_table_schema text, p_table_name text, p_id_column text, p_geom_expr text
+) RETURNS geo.sources
+LANGUAGE plpgsql AS $$
+DECLARE
+  s      geo.sources;
+  t      regclass;
+  idtype text;
+BEGIN
+  t := to_regclass(format('%I.%I', p_table_schema, p_table_name));
+  IF t IS NULL THEN
+    RAISE EXCEPTION 'Table %.% does not exist', p_table_schema, p_table_name USING ERRCODE = 'undefined_table';
+  END IF;
+  SELECT format_type(a.atttypid, a.atttypmod) INTO idtype
+  FROM pg_attribute a
+  WHERE a.attrelid = t AND a.attname = p_id_column AND a.attnum > 0 AND NOT a.attisdropped;
+  IF idtype IS NULL THEN
+    RAISE EXCEPTION 'Column % does not exist on %.%', p_id_column, p_table_schema, p_table_name
+      USING ERRCODE = 'undefined_column';
+  END IF;
+  EXECUTE format('SELECT (%s)::geometry FROM %I.%I r LIMIT 0', p_geom_expr, p_table_schema, p_table_name);
+
+  INSERT INTO geo.sources (name, table_schema, table_name, id_column, id_type, geom_expr)
+  VALUES (p_name, p_table_schema, p_table_name, p_id_column, idtype, p_geom_expr)
+  RETURNING * INTO s;
+
+  EXECUTE format(
+    'CREATE TRIGGER %I AFTER INSERT OR UPDATE OR DELETE ON %I.%I
+     FOR EACH ROW EXECUTE FUNCTION geo.source_row_changed(%L)',
+    'geo_memberships_' || s.id, p_table_schema, p_table_name, s.id::text);
+
+  PERFORM geo.rebuild_memberships(p_name);
+  RETURN s;
+END $$;
+
+CREATE OR REPLACE FUNCTION geo.unregister_source(p_name text) RETURNS void
+LANGUAGE plpgsql AS $$
+DECLARE
+  s geo.sources;
+BEGIN
+  SELECT * INTO s FROM geo.sources WHERE name = p_name;
+  IF s.id IS NULL THEN
+    RAISE EXCEPTION 'Unknown source "%"', p_name USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+  IF to_regclass(format('%I.%I', s.table_schema, s.table_name)) IS NOT NULL THEN
+    EXECUTE format('DROP TRIGGER IF EXISTS %I ON %I.%I', 'geo_memberships_' || s.id, s.table_schema, s.table_name);
+  END IF;
+  DELETE FROM geo.sources WHERE id = s.id;   -- memberships cascade
+END $$;
+
+-- ---------------------------------------------------------------- write helpers
+CREATE OR REPLACE FUNCTION geo.upsert_country(p_code text, p_name text, p_geojson jsonb)
+RETURNS geo.countries
+LANGUAGE plpgsql AS $$
+DECLARE
+  c geo.countries;
+BEGIN
+  INSERT INTO geo.countries (code, name, geom)
+  VALUES (upper(p_code), p_name, CASE WHEN p_geojson IS NULL THEN NULL ELSE geo.geom_from_geojson_area(p_geojson) END)
+  ON CONFLICT (code) DO UPDATE
+    SET name = EXCLUDED.name,
+        geom = coalesce(EXCLUDED.geom, geo.countries.geom)
+  RETURNING * INTO c;
+  RETURN c;
+END $$;
+
+CREATE OR REPLACE FUNCTION geo.upsert_region(
+  p_country_code text,
+  p_slug         text,
+  p_name         text,
+  p_type         geo.region_type,
+  p_level        int,
+  p_parent_id    int,
+  p_code         text,
+  p_tags         text[],
+  p_properties   jsonb,
+  p_geojson      jsonb,
+  p_upsert       boolean DEFAULT true
+) RETURNS geo.regions
+LANGUAGE plpgsql AS $$
+DECLARE
+  r   geo.regions;
+  cid int;
+BEGIN
+  SELECT id INTO cid FROM geo.countries WHERE code = upper(p_country_code);
+  IF cid IS NULL THEN
+    RAISE EXCEPTION 'Unknown country code %', p_country_code USING ERRCODE = 'foreign_key_violation';
+  END IF;
+  IF NOT p_upsert AND EXISTS (SELECT 1 FROM geo.regions WHERE country_id = cid AND slug = p_slug) THEN
+    RAISE EXCEPTION 'A region with slug "%" already exists in %', p_slug, upper(p_country_code)
+      USING ERRCODE = 'unique_violation';
+  END IF;
+
+  INSERT INTO geo.regions (country_id, slug, name, type, level, parent_id, code, tags, properties, geom)
+  VALUES (cid, p_slug, p_name, p_type, p_level, p_parent_id, p_code,
+          coalesce(p_tags, '{}'), coalesce(p_properties, '{}'), geo.geom_from_geojson_area(p_geojson))
+  ON CONFLICT (country_id, slug) DO UPDATE
+    SET name       = EXCLUDED.name,
+        type       = EXCLUDED.type,
+        level      = EXCLUDED.level,
+        parent_id  = EXCLUDED.parent_id,
+        code       = EXCLUDED.code,
+        tags       = EXCLUDED.tags,
+        properties = EXCLUDED.properties,
+        geom       = EXCLUDED.geom
+  RETURNING * INTO r;
+  RETURN r;
+END $$;
+
+CREATE OR REPLACE FUNCTION geo.derive_country_geom(p_code text) RETURNS void
+LANGUAGE plpgsql AS $$
+BEGIN
+  UPDATE geo.countries c
+  SET geom = sub.g
+  FROM (
+    SELECT r.country_id, ST_Multi(ST_UnaryUnion(ST_Collect(r.geom)))::geometry(MultiPolygon,4326) AS g
+    FROM geo.regions r JOIN geo.countries cc ON cc.id = r.country_id
+    WHERE cc.code = upper(p_code) AND r.type = 'admin'
+    GROUP BY r.country_id
+  ) sub
+  WHERE c.id = sub.country_id;
+END $$;
+
+CREATE OR REPLACE FUNCTION geo.regions_at_point(p_lng double precision, p_lat double precision)
+RETURNS SETOF geo.regions
+LANGUAGE sql STABLE AS $$
+  SELECT r.*
+  FROM geo.regions r
+  WHERE ST_Intersects(r.geom, ST_SetSRID(ST_MakePoint(p_lng, p_lat), 4326))
+  ORDER BY r.type, r.level NULLS LAST, r.name;
+$$;
+
+-- ---------------------------------------------------------------- privileges
+-- geom_expr is *trusted SQL*: it is supplied by the database administrator when a
+-- table is registered and is later evaluated inside the membership triggers and in
+-- geo.rebuild_memberships, with the privileges of whichever role happens to be
+-- writing rows or editing regions at that moment. Registering a source is therefore
+-- as powerful as writing a trigger by hand, and must stay an administrative act:
+-- both entry points are taken away from PUBLIC. Everything else in the geo schema
+-- (the query contract, the write helpers) keeps its default grants.
+REVOKE EXECUTE ON FUNCTION geo.register_source(text, text, text, text, text) FROM PUBLIC;
+REVOKE EXECUTE ON FUNCTION geo.unregister_source(text) FROM PUBLIC;

package/sql/004_query_functions.sql

@@ -0,0 +1,95 @@
+-- ============================================================================
+-- 004 — the query contract: ids_in / regions_of
+-- ============================================================================
+
+-- Slugs or numeric ids -> distinct region ids. Raises on any unknown token.
+CREATE OR REPLACE FUNCTION geo.resolve_regions(p_tokens text[]) RETURNS int[]
+LANGUAGE plpgsql STABLE AS $$
+DECLARE
+  ids     int[];
+  unknown text[];
+BEGIN
+  IF p_tokens IS NULL OR cardinality(p_tokens) = 0 THEN
+    RETURN NULL;
+  END IF;
+  SELECT array_agg(t.tok ORDER BY t.n) INTO unknown
+  FROM unnest(p_tokens) WITH ORDINALITY AS t(tok, n)
+  WHERE NOT EXISTS (
+    SELECT 1 FROM geo.regions r
+    WHERE r.slug = t.tok OR r.id = (CASE WHEN t.tok ~ '^\d{1,9}$' THEN t.tok::int END));
+  IF unknown IS NOT NULL THEN
+    RAISE EXCEPTION 'Unknown region(s): %', array_to_string(unknown, ', ')
+      USING ERRCODE = 'invalid_parameter_value', DETAIL = array_to_string(unknown, ',');
+  END IF;
+  SELECT array_agg(DISTINCT r.id) INTO ids
+  FROM geo.regions r
+  JOIN unnest(p_tokens) AS t(tok)
+    ON r.slug = t.tok OR r.id = (CASE WHEN t.tok ~ '^\d{1,9}$' THEN t.tok::int END);
+  RETURN ids;
+END $$;
+
+-- External ids of the source's rows that are inside the given regions
+-- (any of them, or all of them) and inside none of the excluded regions.
+CREATE OR REPLACE FUNCTION geo.ids_in(
+  p_source  text,
+  p_regions text[],
+  p_match   text   DEFAULT 'any',
+  p_exclude text[] DEFAULT NULL
+) RETURNS SETOF text
+LANGUAGE plpgsql STABLE AS $$
+DECLARE
+  sid int;
+  inc int[];
+  exc int[];
+BEGIN
+  SELECT id INTO sid FROM geo.sources WHERE name = p_source;
+  IF sid IS NULL THEN
+    RAISE EXCEPTION 'Unknown source "%"', p_source USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+  IF p_match IS NULL OR p_match NOT IN ('any', 'all') THEN
+    RAISE EXCEPTION 'match must be any or all, got "%"', p_match USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+  inc := geo.resolve_regions(p_regions);
+  IF inc IS NULL THEN
+    RAISE EXCEPTION 'regions must name at least one region' USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+  exc := geo.resolve_regions(p_exclude);
+
+  RETURN QUERY
+    SELECT m.external_id
+    FROM geo.memberships m
+    WHERE m.source_id = sid
+      AND m.region_id = ANY (inc)
+      AND (exc IS NULL OR NOT EXISTS (
+            SELECT 1 FROM geo.memberships x
+            WHERE x.source_id = sid AND x.external_id = m.external_id AND x.region_id = ANY (exc)))
+    GROUP BY m.external_id
+    HAVING p_match = 'any' OR count(DISTINCT m.region_id) = cardinality(inc);
+END $$;
+
+CREATE OR REPLACE FUNCTION geo.region_summary(r geo.regions) RETURNS json
+LANGUAGE sql IMMUTABLE AS $$
+  SELECT json_build_object(
+    'id', r.id, 'slug', r.slug, 'name', r.name, 'type', r.type,
+    'level', r.level, 'parent_id', r.parent_id, 'code', r.code);
+$$;
+
+-- The regions one row of a source belongs to, admin first, as a JSON array.
+-- An unknown source is caller error, not an empty result — same as geo.ids_in.
+CREATE OR REPLACE FUNCTION geo.regions_of(p_source text, p_external_id text) RETURNS json
+LANGUAGE plpgsql STABLE AS $$
+DECLARE
+  sid    int;
+  result json;
+BEGIN
+  SELECT id INTO sid FROM geo.sources WHERE name = p_source;
+  IF sid IS NULL THEN
+    RAISE EXCEPTION 'Unknown source "%"', p_source USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+  SELECT coalesce(json_agg(geo.region_summary(r) ORDER BY r.type, r.level NULLS LAST, r.name), '[]'::json)
+  INTO result
+  FROM geo.memberships m
+  JOIN geo.regions r ON r.id = m.region_id
+  WHERE m.source_id = sid AND m.external_id = p_external_id;
+  RETURN result;
+END $$;