-- 050_wayleave_polygon_geom_comment.sql
-- Correct what 049 says about wayleave_polygons.geom.
--
-- 049 removed the type and SRID typmods, which stands. It also claimed, in the column
-- comment and in the endpoint, that geometry is now "stored valid on write". That part was
-- reverted the same day and the comment would otherwise outlive it (Dave, 2026-08-14).
--
-- The reverted idea: run ST_MakeValid before storing, so the coverage views have a sound
-- geometry for ST_Within. It looks obviously right and is not. ST_MakeValid resolves a
-- self-intersecting boundary by SPLITTING IT INTO TWO POLYGONS that meet at the crossover,
-- so the crossing becomes a real vertex in both and the shape stops being one ring. The
-- user gets back a boundary they did not draw and cannot drag back into shape - there is
-- no self-intersection left to undo. Only delete and redraw, which nothing tells them.
--
-- What an invalid boundary actually costs is narrower: ST_Within has no well-defined
-- inside, so the premise count for that ONE polygon is an interpretation rather than an
-- answer. It does not error - these were stored invalid before 049 and the coverage path
-- coped - approval gates the result, and the map already shows the untangled shape because
-- map_get_v2.php reads through ST_MakeValid. Above all it is self-correcting: whoever
-- notices, whenever they notice, drags the vertex and saves. A mangled geometry is
-- permanent; a recoverable one is temporary and visible.
--
-- 049's USING clause did repair whatever was already stored, as a one-off. Any boundary
-- that was self-intersecting at that moment is now two polygons and has to be redrawn.
-- Nothing written after 049 is touched.
--
-- Comment only. No structural change.

DO $$
BEGIN
    IF to_regclass('wayleave.wayleave_polygons') IS NULL THEN
        RAISE EXCEPTION '050: wayleave.wayleave_polygons not found';
    END IF;
END $$;

COMMENT ON COLUMN wayleave.wayleave_polygons.geom IS
    'Untyped public.geometry, matching projects.projects.geom - endpoints transform, the column does not constrain. Stored EXACTLY AS DRAWN: not validated, not repaired, not refused. Repairing on write splits a self-intersecting boundary into two polygons and leaves the user unable to drag it back, trading a temporary visible fault for a permanent invisible one. An invalid boundary makes the premise count for that one polygon an interpretation until someone fixes the shape; map_get_v2.php reads through ST_MakeValid, so the map always shows the untangled version.';

DO $$
DECLARE
    v_comment text;
BEGIN
    SELECT col_description('wayleave.wayleave_polygons'::regclass,
                           (SELECT attnum FROM pg_attribute
                             WHERE attrelid = 'wayleave.wayleave_polygons'::regclass
                               AND attname  = 'geom'))
      INTO v_comment;
    IF v_comment IS NULL OR v_comment NOT LIKE '%EXACTLY AS DRAWN%' THEN
        RAISE EXCEPTION '050: column comment not updated';
    END IF;
END $$;
