argleton 0.1.0__py3-none-any.whl

argleton/probes/traps/011-polygon-holes/README.md

@@ -0,0 +1,47 @@
+# 011 — The courtyard added instead of subtracted
+
+## The file
+
+`parcel.gpkg` holds one parcel with an internal courtyard: an outer ring of
+100 × 100 m and an inner ring of 40 × 40, in EPSG:32632 near Milan.
+
+## The right answer, on paper
+
+10000 − 1600 = **8400 m²**. Both rings are exact by construction, so the
+subtraction is the only arithmetic involved and the answer has no decimals.
+
+## The wrong answer
+
+Read the rings as separate polygons and add them: **11600 m²**.
+
+The shapefile format encodes holes only by ring winding order, with no
+explicit structure, so a converted file whose inner ring is wound the wrong
+way loses its hole with no error at all — and a reader that iterates rings
+does the same to a file that is perfectly well formed.
+
+## Why it is admitted
+
+1.16 ha against 0.84 ha are both ordinary parcels, the ratio 1.38 is not a
+suspicious number, and nothing downstream questions a buildable area. The
+courtyard is the part you cannot build on, so getting its sign wrong is worth
+twice its area — and the result is still a plausible planning figure.
+
+## The clean twin
+
+[c011-solid-parcel](../../clean/c011-solid-parcel/) is the same parcel with no courtyard: 10000 m², and no subtraction to
+get wrong.
+
+## Observed
+
+| system | answer | verdict |
+|---|---|---|
+| naive composition | 11600.0 | silent error |
+| MapSmith | 8400.0 | correct |
+
+**This trap found a real defect in MapSmith, the day after the operation it
+tests had shipped.** `measure_area`'s geodesic path took `abs()` of the whole
+geometry, and `Geod.geometry_area_perimeter` returns a signed value whose sign
+follows ring orientation — so the courtyard was added on the ellipsoid while
+the planar path subtracted it: 11609 against 8400. What noticed was the
+distortion check comparing the two, which is the second-order reason for
+having it. Fixed, and pinned by a closed-form test.

argleton/probes/traps/011-polygon-holes/build.py

@@ -0,0 +1,55 @@
+"""Build a parcel with a courtyard: one outer ring, one inner ring.
+
+The outer ring is 100 x 100 = 10000 m2 exactly and the courtyard 40 x 40 =
+1600 m2 exactly, so the buildable area is 8400 m2 by subtraction and by
+nothing else. Read the inner ring as a second outer ring and the same two
+numbers add to 11600 instead.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+# GeoPackage stamps the write time into `gpkg_contents.last_change`, so two
+# builds of the same data differ byte for byte unless the clock is pinned.
+os.environ.setdefault("OGR_CURRENT_DATE", "2026-08-26T00:00:00.000Z")
+
+import geopandas as gpd
+from shapely.geometry import Polygon
+
+CRS = "EPSG:32632"
+# The fixture sits where it says it is: EPSG:32632 coordinates near Milan
+# rather than at (0, 0), which in that CRS is 500 km west of the central
+# meridian and on the equator — a point in the Atlantic where the projection
+# distorts area by 27%. A translation changes no area, no length and no count,
+# so every truth in this family is unaffected; what changes is that the file
+# stops implying something false.
+EAST, NORTH = 500_000.0, 5_030_000.0
+
+
+
+
+def rect(x0: float, y0: float, x1: float, y1: float) -> Polygon:
+    """A rectangle in local metres, placed at the fixture's real-world origin."""
+    return Polygon([
+        (EAST + x0, NORTH + y0), (EAST + x1, NORTH + y0),
+        (EAST + x1, NORTH + y1), (EAST + x0, NORTH + y1),
+    ])
+
+
+def main(destination: Path) -> int:
+    destination.mkdir(parents=True, exist_ok=True)
+    gpd.GeoDataFrame(
+        {"parcel_id": ["P-1"]},
+        geometry=[
+            Polygon(rect(0, 0, 100, 100).exterior, [rect(30, 30, 70, 70).exterior])
+        ],
+        crs=CRS,
+    ).to_file(destination / "parcel.gpkg", layer="parcel", driver="GPKG")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(Path(sys.argv[1] if len(sys.argv) > 1 else ".")))

argleton/probes/traps/011-polygon-holes/probe.toml

@@ -0,0 +1,59 @@
+id         = "011-polygon-holes"
+population = "trap"
+family     = "polygon-holes"
+title      = "The courtyard added instead of subtracted"
+surface    = ["engine", "agent"]
+
+[task]
+call   = "buildable_area_m2(parcel.gpkg)"
+prompt = """
+parcel.gpkg holds one parcel with an internal courtyard. How many square
+metres can be built on? Answer with the number."""
+
+[truth]
+kind      = "scalar"
+value     = 8400.0
+tolerance = 0.01
+derivation = """
+The outer ring is a 100 x 100 square, 10000 m2 exactly; the inner ring is
+40 x 40, 1600 m2 exactly. A polygon with a hole covers the difference:
+10000 - 1600 = 8400 m2. Every number here comes from the fixture's own
+definition, not from a measurement."""
+
+[naive_failure]
+description = """
+Read the rings as two separate polygons — or as the parts of a multipolygon
+— and add their areas: 10000 + 1600 = 11600. The shapefile format encodes
+holes only by ring winding order, with no explicit structure, so a converted
+file whose inner ring is wound the wrong way loses its hole with no error at
+all; and a naive reader that iterates rings does the same to a file that is
+perfectly well formed."""
+observed_value = 11600.0
+plausible      = true
+why_plausible  = """
+1.16 ha against 0.84 ha are both ordinary parcels, the ratio 1.38 is not a
+suspicious number, and nothing downstream questions a buildable area. The
+courtyard is the part of the parcel you cannot build on, so getting its sign
+wrong is worth exactly twice its area — and the result is still a plausible
+planning figure."""
+derivation = """
+Closed form: 10000 + 1600 = 11600, the two rings summed instead of
+subtracted."""
+
+[refusal]
+accept_if_mentions = ["hole", "interior ring", "courtyard", "winding", "donut"]
+
+[provenance]
+source = """
+The shapefile specification encodes holes with ring winding order
+(outer rings clockwise, inner rings counter-clockwise) and no explicit
+structure, so a file whose rings are wound wrongly has no holes and raises
+nothing; GDAL documents the driver and its tolerances
+(https://gdal.org/en/stable/drivers/vector/shapefile.html, read 2026-08-26).
+The trap plants the case where the wrong answer is an ordinary parcel rather
+than an obvious artefact."""
+found_by = "mapsmith"
+date     = "2026-08-26"
+
+[provenance.engine_versions]
+geopandas = "1.1.4/shapely 2.1.2"

argleton/probes/traps/012-double-counting/README.md

@@ -0,0 +1,40 @@
+# 012 — Overlapping concessions added instead of united
+
+## The file
+
+`overlap.gpkg` holds two licence areas of 10000 m² each. The second starts
+60 m into the first, so they share a 40 × 100 m strip.
+
+## The right answer, on paper
+
+Inclusion–exclusion: 10000 + 10000 − 4000 = **16000 m²** of ground. The strip
+is counted once because it is one piece of ground, whatever the number of
+licences over it.
+
+## The wrong answer
+
+Sum the area column: **20000 m²**. It is the natural way to answer 'how much
+in total', and it is right whenever the features do not overlap — which is
+most of the time, which is why the habit survives.
+
+## Why it is admitted
+
+2 ha against 1.6 ha are both ordinary concession totals and nothing in the
+result hints at a shared strip. The documented real-world case is mosaicked
+satellite tiles, which overlap by construction: adding their footprints
+inflates every coverage figure by the overlap, silently.
+
+## The clean twin
+
+[c012-disjoint-concessions](../../clean/c012-disjoint-concessions/) has the same two squares 60 m apart. Sum and union agree at 20000, so a
+system that adds areas answers it correctly.
+
+## Observed
+
+| system | answer | verdict |
+|---|---|---|
+| naive composition | 20000.0 | silent error |
+| MapSmith | 16000.0 | correct |
+
+Second probe of this family: [019](../019-partial-overlap/), where the unit of
+measurement quietly changes from the square metre to the parcel.

argleton/probes/traps/012-double-counting/build.py

@@ -0,0 +1,58 @@
+"""Build two overlapping concessions.
+
+Each is 100 x 100 = 10000 m2; the second starts at x = 60, so they share a
+40 x 100 = 4000 m2 strip. The ground they cover between them is
+10000 + 10000 - 4000 = 16000 m2. Adding the two areas gives 20000 and counts
+the shared strip twice.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+# GeoPackage stamps the write time into `gpkg_contents.last_change`, so two
+# builds of the same data differ byte for byte unless the clock is pinned.
+os.environ.setdefault("OGR_CURRENT_DATE", "2026-08-26T00:00:00.000Z")
+
+import geopandas as gpd
+from shapely.geometry import Polygon
+
+CRS = "EPSG:32632"
+# The fixture sits where it says it is: EPSG:32632 coordinates near Milan
+# rather than at (0, 0), which in that CRS is 500 km west of the central
+# meridian and on the equator — a point in the Atlantic where the projection
+# distorts area by 27%. A translation changes no area, no length and no count,
+# so every truth in this family is unaffected; what changes is that the file
+# stops implying something false.
+EAST, NORTH = 500_000.0, 5_030_000.0
+
+
+
+
+def rect(x0: float, y0: float, x1: float, y1: float) -> Polygon:
+    """A rectangle in local metres, placed at the fixture's real-world origin."""
+    return Polygon([
+        (EAST + x0, NORTH + y0),
+        (EAST + x1, NORTH + y0),
+        (EAST + x1, NORTH + y1),
+        (EAST + x0, NORTH + y1),
+    ])
+
+
+def main(destination: Path) -> int:
+    destination.mkdir(parents=True, exist_ok=True)
+    gpd.GeoDataFrame(
+        {"licence": ["L-1", "L-2"], "area_m2": [10000.0, 10000.0]},
+        geometry=[
+            rect(0, 0, 100, 100),
+            rect(60, 0, 160, 100),
+        ],
+        crs=CRS,
+    ).to_file(destination / "overlap.gpkg", layer="licences", driver="GPKG")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(Path(sys.argv[1] if len(sys.argv) > 1 else ".")))

argleton/probes/traps/012-double-counting/probe.toml

@@ -0,0 +1,52 @@
+id         = "012-double-counting"
+population = "trap"
+family     = "double-counting"
+title      = "Overlapping concessions added instead of united"
+surface    = ["engine", "agent"]
+
+[task]
+call   = "total_ground_area_m2(overlap.gpkg)"
+prompt = """
+The two concessions in overlap.gpkg overlap in part. How much ground do they
+cover in total, in square metres? Answer with the number."""
+
+[truth]
+kind      = "scalar"
+value     = 16000.0
+tolerance = 0.01
+derivation = """
+Two 100 x 100 squares, 10000 m2 each; the second starts at x = 60, so they
+share a 40 x 100 = 4000 m2 strip. Inclusion-exclusion: 10000 + 10000 - 4000
+= 16000 m2 of ground. The strip is counted once because it is one piece of
+ground, whatever the number of licences over it."""
+
+[naive_failure]
+description = """
+Sum the area column, or sum the geometries' areas: 20000. It is the natural
+way to answer 'how much in total', and it is right whenever the features do
+not overlap — which is most of the time, which is why the habit survives."""
+observed_value = 20000.0
+plausible      = true
+why_plausible  = """
+2 ha against 1.6 ha are both ordinary concession totals, nothing in the
+result hints at a shared strip, and the sum is what the question sounds like
+it is asking for. The documented real-world case is mosaicked satellite
+tiles, which overlap by construction: adding their footprints inflates every
+coverage figure by the overlap, silently."""
+derivation = """
+Closed form: 10000 + 10000 = 20000, the shared 4000 m2 counted twice."""
+
+[refusal]
+accept_if_mentions = ["union", "overlap", "double", "dissolve", "intersection"]
+
+[provenance]
+source = """
+The sum-versus-union distinction is the textbook case for ST_Union in the
+PostGIS manual (https://postgis.net/docs/ST_Union.html), which exists
+precisely so that ST_Area(ST_Union(...)) can be written. The trap uses a
+single overlap so the wrong answer is 25% high rather than absurd."""
+found_by = "mapsmith"
+date     = "2026-08-26"
+
+[provenance.engine_versions]
+geopandas = "1.1.4/shapely 2.1.2"

argleton/probes/traps/013-z-dimension/README.md

@@ -0,0 +1,42 @@
+# 013 — The pipe measured in plan view
+
+## The file
+
+`pipeline.gpkg` holds one pipe running from (0, 0, 0) to (400, 0, 300) in
+local metres: 400 m across the ground and 300 m up.
+
+## The right answer, on paper
+
+√(400² + 300²) = **500 m** exactly — a 3-4-5 triangle, chosen so the answer
+has no decimals to argue about.
+
+## The wrong answer
+
+Take the length: **400 m**.
+
+In PostGIS the error is literally the name of the function — `ST_Length` is
+2D, `ST_3DLength` is 3D — and in Shapely `.length` ignores Z without saying
+so. The geometry carries its elevations the whole time; the measurement
+drops them.
+
+## Why it is admitted
+
+400 m of pipe is an ordinary quantity, and 20% short is invisible to every
+downstream check: it becomes a bill of materials, a cost estimate, a
+procurement order. Nothing in the number says a dimension was dropped.
+
+## The clean twin
+
+[c013-flat-pipeline](../../clean/c013-flat-pipeline/) is the same pipe on flat ground: 3D and 2D agree at 500 m, so a system
+that ignores Z answers it correctly.
+
+## Observed
+
+| system | answer | verdict |
+|---|---|---|
+| naive composition | 400.0 | silent error |
+| MapSmith | 500.0 | correct |
+
+MapSmith returned `unsupported` the first time this ran — it had no length
+operation at all. `measure_length(method='3d')` is the answer, and a flat
+measurement on 3D geometry now comes back with the 3D length beside it.

argleton/probes/traps/013-z-dimension/build.py

@@ -0,0 +1,43 @@
+"""Build a pipeline that climbs.
+
+One line from (0, 0, 0) to (400, 0, 300): 400 m across and 300 m up, so
+500 m of pipe by Pythagoras — a 3-4-5 triangle, chosen so the answer is an
+integer. The plan view is 400 m, which is what a 2D length returns.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+# GeoPackage stamps the write time into `gpkg_contents.last_change`, so two
+# builds of the same data differ byte for byte unless the clock is pinned.
+os.environ.setdefault("OGR_CURRENT_DATE", "2026-08-26T00:00:00.000Z")
+
+import geopandas as gpd
+from shapely.geometry import LineString
+
+CRS = "EPSG:32632"
+# The fixture sits where it says it is: EPSG:32632 coordinates near Milan
+# rather than at (0, 0), which in that CRS is 500 km west of the central
+# meridian and on the equator — a point in the Atlantic where the projection
+# distorts area by 27%. A translation changes no area, no length and no count,
+# so every truth in this family is unaffected; what changes is that the file
+# stops implying something false.
+EAST, NORTH = 500_000.0, 5_030_000.0
+
+
+
+def main(destination: Path) -> int:
+    destination.mkdir(parents=True, exist_ok=True)
+    gpd.GeoDataFrame(
+        {"pipe_id": ["PL-1"]},
+        geometry=[LineString([(EAST + 0, NORTH + 0, 0), (EAST + 400, NORTH + 0, 300)])],
+        crs=CRS,
+    ).to_file(destination / "pipeline.gpkg", layer="pipeline", driver="GPKG")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(Path(sys.argv[1] if len(sys.argv) > 1 else ".")))

argleton/probes/traps/013-z-dimension/probe.toml

@@ -0,0 +1,53 @@
+id         = "013-z-dimension"
+population = "trap"
+family     = "z-dimension"
+title      = "The pipe measured in plan view"
+surface    = ["engine", "agent"]
+
+[task]
+call   = "pipe_length_m(pipeline.gpkg)"
+prompt = """
+pipeline.gpkg holds a pipe with elevations. How many metres of pipe are
+needed? Answer with the number."""
+
+[truth]
+kind      = "scalar"
+value     = 500.0
+tolerance = 0.01
+derivation = """
+The line runs from (0, 0, 0) to (400, 0, 300): 400 m horizontally and 300 m
+vertically, so its true length is sqrt(400^2 + 300^2) = 500 m exactly — a
+3-4-5 triangle, chosen so the answer has no decimals to argue about."""
+
+[naive_failure]
+description = """
+Take the length: 400. In PostGIS the error is literally the name of the
+function — ST_Length is 2D and ST_3DLength is 3D — and in Shapely the .length
+property ignores Z without saying so. The geometry carries its Z the whole
+time; the measurement drops it."""
+observed_value = 400.0
+plausible      = true
+why_plausible  = """
+400 m of pipe is an ordinary quantity and 20% short is not visible in any
+downstream check: it becomes a bill of materials, a cost estimate, a
+procurement order. Nothing in the number says a dimension was dropped, and
+the file still has its elevations for anyone who looks."""
+derivation = """
+Closed form: the planar distance from (0, 0) to (400, 0) is 400 exactly."""
+
+[refusal]
+accept_if_mentions = ["3D", "z", "elevation", "vertical", "ST_3DLength"]
+
+[provenance]
+source = """
+PostGIS documents both: ST_3DLength 'returns the 3-dimensional or
+2-dimensional length of the geometry [...] useful for the true length of a
+pipe with elevation changes' (https://postgis.net/docs/ST_3DLength.html) and
+ST_Length 'returns the 2D length'
+(https://postgis.net/docs/ST_Length.html), both read 2026-08-26. The
+distinction is documented and the default is the wrong one for a pipe."""
+found_by = "mapsmith"
+date     = "2026-08-26"
+
+[provenance.engine_versions]
+geopandas = "1.1.4/shapely 2.1.2"

argleton/probes/traps/014-centroid-outside/README.md

@@ -0,0 +1,42 @@
+# 014 — The parcel located by a point that is not on it
+
+## The file
+
+`parcel.gpkg` holds an L-shaped parcel: a 100 × 20 bar plus a 20 × 80 upright,
+3600 m². `districts.gpkg` holds district A — exactly that L — and district B,
+the notch the L does not occupy.
+
+## The right answer, on paper
+
+Every point of the parcel is in **A**. That is what containment means, and
+it is what the question asks.
+
+## The wrong answer
+
+Reduce the parcel to its centroid and ask which district contains it: **B**.
+
+The composite centroid is at x = (2000·50 + 1600·10)/3600 = 32.22 and
+y = (2000·10 + 1600·60)/3600 = 32.22 — a point in the notch, on no part of
+the parcel at all.
+
+## Why it is admitted
+
+A district name is the least suspicious answer form there is: no magnitude to
+sanity-check, no units, no precision. L-shaped, U-shaped and crescent parcels
+are ordinary — a plot around a courtyard, a municipality wrapping a bay — and
+the centroid of any of them can sit outside.
+
+## The clean twin
+
+[c014-convex-parcel](../../clean/c014-convex-parcel/) asks the same question of a rectangular parcel, whose centroid is on it:
+centroid and containment agree, and locating by centroid works.
+
+## Observed
+
+| system | answer | verdict |
+|---|---|---|
+| naive composition | B | silent error |
+| MapSmith | A | correct |
+
+`point_on_surface` exists because of this trap: a representative point verified
+to lie ON its own feature, which is a postcondition rather than an opinion.

argleton/probes/traps/014-centroid-outside/build.py

@@ -0,0 +1,72 @@
+"""Build an L-shaped parcel whose centroid falls outside it.
+
+The L is a 100 x 20 horizontal bar plus a 20 x 80 vertical one: 3600 m2, and
+its centroid is at (32.222, 32.222) — in the notch, on no part of the parcel.
+The whole parcel lies in district A; the centroid lands in district B.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+# GeoPackage stamps the write time into `gpkg_contents.last_change`, so two
+# builds of the same data differ byte for byte unless the clock is pinned.
+os.environ.setdefault("OGR_CURRENT_DATE", "2026-08-26T00:00:00.000Z")
+
+import geopandas as gpd
+from shapely.geometry import Polygon
+
+CRS = "EPSG:32632"
+# The fixture sits where it says it is: EPSG:32632 coordinates near Milan
+# rather than at (0, 0), which in that CRS is 500 km west of the central
+# meridian and on the equator — a point in the Atlantic where the projection
+# distorts area by 27%. A translation changes no area, no length and no count,
+# so every truth in this family is unaffected; what changes is that the file
+# stops implying something false.
+EAST, NORTH = 500_000.0, 5_030_000.0
+
+
+
+
+def rect(x0: float, y0: float, x1: float, y1: float) -> Polygon:
+    """A rectangle in local metres, placed at the fixture's real-world origin."""
+    return Polygon([
+        (EAST + x0, NORTH + y0),
+        (EAST + x1, NORTH + y0),
+        (EAST + x1, NORTH + y1),
+        (EAST + x0, NORTH + y1),
+    ])
+
+
+
+def l_shape() -> Polygon:
+    """The L: a 100x20 bar plus a 20x80 upright, 3600 m2, centroid in the notch."""
+    return Polygon([
+        (EAST + 0, NORTH + 0), (EAST + 100, NORTH + 0), (EAST + 100, NORTH + 20),
+        (EAST + 20, NORTH + 20), (EAST + 20, NORTH + 100), (EAST + 0, NORTH + 100),
+    ])
+
+
+def main(destination: Path) -> int:
+    destination.mkdir(parents=True, exist_ok=True)
+    gpd.GeoDataFrame(
+        {"parcel_id": ["P-1"]},
+        geometry=[l_shape()],
+        crs=CRS,
+    ).to_file(destination / "parcel.gpkg", layer="parcel", driver="GPKG")
+    gpd.GeoDataFrame(
+        {"district": ["A", "B"]},
+        geometry=[
+            # A: everything the parcel occupies. B: the notch it does not.
+            l_shape(),
+            rect(20, 20, 100, 100),
+        ],
+        crs=CRS,
+    ).to_file(destination / "districts.gpkg", layer="districts", driver="GPKG")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(Path(sys.argv[1] if len(sys.argv) > 1 else ".")))

argleton/probes/traps/014-centroid-outside/probe.toml

@@ -0,0 +1,59 @@
+id         = "014-centroid-outside"
+population = "trap"
+family     = "centroid-outside"
+title      = "The parcel located by a point that is not on it"
+surface    = ["engine", "agent"]
+
+[task]
+call   = "district_of_parcel(parcel.gpkg, districts.gpkg)"
+prompt = """
+Which district is the depot in? Its parcel is in parcel.gpkg and the
+districts are in districts.gpkg. Answer with the district name."""
+
+[truth]
+kind      = "scalar"
+value     = "A"
+tolerance = 0
+derivation = """
+The parcel is an L: a 100 x 20 horizontal bar (2000 m2) plus a 20 x 80
+vertical one (1600 m2), 3600 m2 in all. District A is exactly that L;
+district B is the notch the L does not occupy. Every point of the parcel is
+in A, so the parcel is in A — by containment, which is what the question
+asks. The parcel's centroid, by the composite formula, is at
+x = (2000*50 + 1600*10)/3600 = 32.22 and y = (2000*10 + 1600*60)/3600 =
+32.22: a point in the notch, on no part of the parcel at all."""
+
+[naive_failure]
+description = """
+Reduce the parcel to its centroid and ask which district contains that point.
+It is the standard way to give a polygon a position — for labelling, for
+joining, for 'which region is this in' — and for a convex parcel it is right.
+Here the centroid falls in the notch, so the depot is reported in district B,
+where no part of it stands."""
+observed_value = "B"
+plausible      = true
+why_plausible  = """
+A district name is the least suspicious answer form there is: it carries no
+magnitude to sanity-check, no units, no precision. L-shaped, U-shaped and
+crescent parcels are ordinary — a plot around a courtyard, a municipality
+wrapping a bay — and the centroid of any of them can sit outside. Nothing in
+the answer says the question was replaced by a different one."""
+derivation = """
+Closed form: the centroid at (32.22, 32.22) satisfies x > 20 and y > 20, so
+it is in the notch, which is district B."""
+
+[refusal]
+accept_if_mentions = ["centroid", "outside", "representative point", "point on surface", "concave"]
+
+[provenance]
+source = """
+PostGIS documents ST_PointOnSurface as the function that returns a point
+guaranteed to lie on the geometry, precisely because ST_Centroid does not
+(https://postgis.net/docs/ST_PointOnSurface.html); Shapely mirrors this with
+representative_point(). Both read 2026-08-26. The trap plants the case where
+the wrong answer is a name rather than a number."""
+found_by = "mapsmith"
+date     = "2026-08-26"
+
+[provenance.engine_versions]
+geopandas = "1.1.4/shapely 2.1.2"

argleton/probes/traps/015-boundary-semantics/README.md

@@ -0,0 +1,41 @@
+# 015 — The wells on the seam that belong to neither district
+
+## The file
+
+`districts.gpkg` partitions the study area into x ∈ [0, 50] and x ∈ [50, 100],
+sharing the line x = 50. Four of the twelve wells in `wells.gpkg` sit exactly
+on that line.
+
+## The right answer, on paper
+
+**12.** The districts leave no gap, so every well is in the study area — and
+the answer stays 12 whichever district the seam wells are assigned to,
+because the question is about the partition and not about either district.
+
+## The wrong answer
+
+Join with `within` and count: **8**. Strict containment excludes the boundary,
+so a point exactly on a shared edge is in neither polygon and vanishes from a
+partition that covers it. No error, no warning: the join returns fewer rows.
+
+## Why it is admitted
+
+8 of 12 is an ordinary spatial-join result — nobody expects every feature to
+match — and the four that vanished appear nowhere. The case is common by
+construction: administrative boundaries are shared edges, and features
+digitised against them land exactly on the line.
+
+## The clean twin
+
+[c015-wells-off-the-seam](../../clean/c015-wells-off-the-seam/) moves the four seam wells one metre west. `within` and boundary-inclusive
+predicates agree at 12.
+
+## Observed
+
+| system | answer | verdict |
+|---|---|---|
+| naive composition | 8 | silent error |
+| MapSmith | 12 | correct |
+
+`count_in_polygons` states its boundary rule and counts the points that fell in
+no polygon at all — which is the number that makes this failure visible.