argleton 0.1.0__py3-none-any.whl

argleton/probes/schema/result.schema.json

@@ -0,0 +1,103 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://argleton.org/schema/result-v1.schema.json",
+  "title": "Argleton result",
+  "description": "One run of the suite against one system. The shape is a claim: a result that reports a silent-error rate without the completion rate beside it is not a valid result, because a system that refuses everything scores perfectly on the first and is useless.",
+  "type": "object",
+  "required": [
+    "system", "adapter", "spec_commit", "date",
+    "silent_error_rate", "completion_rate",
+    "traps_run", "clean_run", "unsupported", "by_family", "per_probe"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "system": {
+      "type": "string",
+      "minLength": 1,
+      "description": "What was measured, as its authors would name it — not the adapter's convenience label."
+    },
+    "adapter": {
+      "type": "string",
+      "description": "How it was asked. Two adapters for one system can legitimately disagree, and a result that does not say which was used cannot be reproduced."
+    },
+    "spec_commit": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{7,40}(-dirty)?$",
+      "description": "The commit the probes, tolerances and method were at. This is the pre-registration: whether a rule moved after a number was seen is answered by a diff rather than by our word. A `-dirty` suffix means the tree was modified and the result is not reproducible from any commit."
+    },
+    "date": {"type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"},
+
+    "silent_error_rate": {
+      "type": ["number", "null"],
+      "minimum": 0, "maximum": 1,
+      "description": "Traps answered wrongly and presented as successful, over traps run. The metric. Null only when no trap ran, which is a report about the adapter and not about the system."
+    },
+    "completion_rate": {
+      "type": ["number", "null"],
+      "minimum": 0, "maximum": 1,
+      "description": "Clean probes answered correctly, over clean probes run. Required beside the rate above, always. Quoting one without the other is the one thing this format exists to prevent."
+    },
+    "traps_run": {
+      "type": "integer", "minimum": 0,
+      "description": "Denominator, published with the rate. An adapter that skipped half the suite must not be able to look better than one that faced all of it."
+    },
+    "clean_run": {"type": "integer", "minimum": 0},
+    "unsupported": {
+      "type": "integer", "minimum": 0,
+      "description": "Probes the adapter cannot express. Counted apart from both rates: scoring an operation a system was never asked to perform would measure the adapter."
+    },
+
+    "verdict_counts": {
+      "type": "object",
+      "additionalProperties": {"type": "integer", "minimum": 0},
+      "description": "How the outcomes fell across the seven verdicts. Absent keys are zero."
+    },
+    "by_family": {
+      "type": "object",
+      "description": "Per family, so one family with ten probes cannot read as ten independent findings.",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["probes", "silent_errors"],
+        "additionalProperties": false,
+        "properties": {
+          "probes": {"type": "integer", "minimum": 0},
+          "silent_errors": {"type": "integer", "minimum": 0}
+        }
+      }
+    },
+
+    "per_probe": {
+      "type": "array",
+      "description": "Every probe, whatever it did. A result that publishes only the failures, or only the successes, is an argument rather than a measurement.",
+      "items": {
+        "type": "object",
+        "required": ["probe_id", "population", "family", "verdict", "detail"],
+        "additionalProperties": false,
+        "properties": {
+          "probe_id": {"type": "string"},
+          "population": {"enum": ["trap", "clean"]},
+          "family": {"type": "string"},
+          "verdict": {
+            "enum": [
+              "correct", "correct_with_warning", "refused_correctly",
+              "noisy_failure", "refused_wrongly", "silent_error", "unsupported"
+            ]
+          },
+          "detail": {
+            "type": "string",
+            "description": "What happened, in enough words to argue with. A verdict without one is a score."
+          },
+          "answer": {"description": "What the system returned, when it returned anything."},
+          "repetitions": {
+            "type": "integer", "minimum": 1,
+            "description": "How many times this probe was run. The engine tier is deterministic and runs once; the agent tier has variance and must not be reported from a single run."
+          },
+          "spread": {
+            "type": ["number", "null"],
+            "description": "Observed variation across repetitions, when there were any. An agent-tier number without it is an anecdote."
+          }
+        }
+      }
+    }
+  }
+}

argleton/probes/traps/001-tiff-predictor/README.md

@@ -0,0 +1,75 @@
+# 001 — TIFF horizontal predictor is not undone on read
+
+## The file
+
+`dem.tif` is an ordinary GeoTIFF: 32×32, int16 elevations, EPSG:32632, 30 m
+pixels, deflate compression, **predictor 2**.
+
+Predictor 2 is TIFF tag 317 set to `2`, horizontal differencing. Before
+compressing, each sample is replaced by the difference from its left neighbour,
+because the differences of a smooth surface compress far better than the values.
+It is standard, it is what GDAL writes when you ask for it, and undoing it on
+read is the reader's job — not an optional optimisation.
+
+`dem_plain.tif` holds the identical elevations without the predictor. A
+conforming reader returns the same array from both, and it is in the fixture so
+that anyone can check that in one line.
+
+## The right answer, on paper
+
+The elevations are defined in `build.py` as
+
+```
+v[i,j] = 1000 + 4j + 2i      i, j = 0..31
+```
+
+so the mean is `1000 + 4·mean(j) + 2·mean(i) = 1000 + 4·15.5 + 2·15.5` = **1093.0**
+exactly. No reference implementation is consulted: it is arithmetic on the
+definition. That matters — a truth obtained by running some other library
+measures agreement with that library, and the day it has the same bug, the
+suite certifies it.
+
+## The wrong answer, also on paper
+
+A reader that returns the stored differences sees `v[i,0]` in the first column
+and a constant `4` everywhere else. Summing along row `i` telescopes:
+
+```
+v[i,0] + Σ (v[i,j] − v[i,j−1]) = v[i,31]
+```
+
+so the total is `Σ_i v[i,31] = 32 · (1124 + 2·15.5) = 32 · 1155`, and the mean is
+`36960 / 1024` = **36.09375** — the mean of the last column divided by the width.
+
+The wrong answer is not noise. It is a different, predictable statistic, which
+is exactly why a system can produce it with complete confidence.
+
+## Why it is admitted
+
+36 m is an unremarkable mean elevation. No NaN, no negative, no nodata sentinel,
+no exception. The grid the number came from still renders as terrain; hillshade
+over it still looks like hillshade and flow accumulation still flows downhill,
+which is how the upstream bug was noticed at all — not because anything failed,
+but because the terrain was subtly the wrong terrain.
+
+Only a comparison against the true elevations reveals it, and nothing in an
+ordinary workflow performs that comparison.
+
+## Observed
+
+| system | answer |
+|---|---|
+| rasterio / GDAL | 1093.0 ✓ |
+| whitebox-workflows | 36.09375 ✗ |
+
+Reproduced 2026-08-23. Upstream report:
+<https://github.com/jblindsay/whitebox_next_gen/issues/32>.
+
+If upstream fixes this, the probe does not stop being useful: it becomes a
+regression test with a date on it.
+
+## Clean twin
+
+`clean/c001-raster-mean` — the same elevations, stored plainly. Without it, a
+silent-error rate on this family could not be told apart from "the system cannot
+open the file at all".

argleton/probes/traps/001-tiff-predictor/build.py

@@ -0,0 +1,58 @@
+"""Build a valid GeoTIFF whose bytes are horizontally differenced.
+
+The file is ordinary. TIFF's horizontal predictor (tag 317 = 2) stores each
+pixel as the difference from its left neighbour before compressing, because
+differences of a smooth surface compress far better than the values themselves.
+Undoing it on read is the reader's job, and it is not optional.
+
+The elevations are chosen so that both the right answer and the wrong one can be
+worked out on paper — see README.md. That is the point of a fixture that is
+built rather than vendored: nothing here has to be taken on trust.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import numpy as np
+import rasterio
+from rasterio.transform import from_origin
+
+HEIGHT = WIDTH = 32
+WEST, NORTH, PIXEL = 500000.0, 5000000.0, 30.0  # UTM 32N, 30 m — SRTM-shaped
+BASE, EAST_STEP, SOUTH_STEP = 1000, 4, 2
+
+
+def elevations() -> np.ndarray:
+    """A plateau tilting east and south. int16, like SRTM and most public DEMs.
+
+    Integers matter: TIFF predictor 2 is defined for integer samples, so this is
+    an ordinary file and not a malformed one. A reader that gets it wrong is not
+    being fed something exotic.
+    """
+    row, column = np.mgrid[0:HEIGHT, 0:WIDTH]
+    return (BASE + EAST_STEP * column + SOUTH_STEP * row).astype("int16")
+
+
+def main(destination: Path) -> int:
+    destination.mkdir(parents=True, exist_ok=True)
+    grid = elevations()
+    profile = dict(
+        driver="GTiff", height=HEIGHT, width=WIDTH, count=1, dtype="int16",
+        crs="EPSG:32632", nodata=-32768,
+        transform=from_origin(WEST, NORTH, PIXEL, PIXEL),
+    )
+    # The trap: same pixels, stored differenced. A conforming reader returns
+    # identical arrays from both files, and `dem_plain.tif` is here so that
+    # anyone can check that in one line.
+    with rasterio.open(destination / "dem_plain.tif", "w", **profile) as ds:
+        ds.write(grid, 1)
+    with rasterio.open(destination / "dem.tif", "w", **profile,
+                       compress="deflate", predictor=2) as ds:
+        ds.write(grid, 1)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(Path(sys.argv[1] if len(sys.argv) > 1 else ".")))

argleton/probes/traps/001-tiff-predictor/probe.toml

@@ -0,0 +1,57 @@
+id         = "001-tiff-predictor"
+population = "trap"
+family     = "raster-encoding"
+title      = "TIFF horizontal predictor is not undone on read"
+surface    = ["engine", "agent"]
+
+[task]
+call   = "raster_mean(dem.tif)"
+prompt = "What is the mean elevation of dem.tif, in metres?"
+
+[truth]
+kind      = "scalar"
+value     = 1093.0
+tolerance = 0.001
+derivation = """
+The DEM is v[i,j] = 1000 + 4j + 2i over a 32x32 grid, so the mean is
+1000 + 4*mean(j) + 2*mean(i) = 1000 + 4*15.5 + 2*15.5 = 1093 exactly.
+No reference implementation is involved: the value is arithmetic on the
+definition in build.py."""
+
+[naive_failure]
+description = """
+The reader returns the stored differences instead of the elevations. Along each
+row the values become v[i,0], then v[i,1]-v[i,0], v[i,2]-v[i,1], ... — a
+constant 4 everywhere except the first column. The surface still looks like a
+surface; it is simply a different one."""
+observed_value = 36.09375
+plausible      = true
+why_plausible  = """
+36 m is an unremarkable mean elevation. Nothing about the answer is malformed:
+no NaN, no negative, no nodata sentinel, no exception, and the raster it came
+from is still a well-formed grid that renders as terrain. Derived products
+inherit the same property, which is how the upstream bug was found: hillshade
+and flow accumulation over the differenced grid look like hillshade and flow
+accumulation. Only comparing against the true elevations reveals it, and
+nothing in an ordinary workflow does that."""
+derivation = """
+Also closed form. Summing the differenced values along row i telescopes to
+v[i,31], so the total is sum_i v[i,31] = 32 * (1124 + 2*15.5) = 32 * 1155,
+and the mean is 36960 / 1024 = 36.09375 exactly — the mean of the last column
+divided by the width. The wrong answer is not noise: it is a different,
+predictable statistic, which is why a system can produce it with confidence."""
+
+[refusal]
+# A refusal only counts when it names the real defect. "This file looks odd"
+# about a file that is odd for a reason the system never found is a lucky guess.
+accept_if_mentions = ["predictor", "tag 317", "differenc", "horizontal prediction"]
+
+[provenance]
+source   = "https://github.com/jblindsay/whitebox_next_gen/issues/32"
+found_by = "mapsmith"
+date     = "2026-08-20"
+
+[provenance.engine_versions]
+whitebox_workflows = "reproduced 2026-08-23: mean 36.094 instead of 1093.0"
+rasterio           = "correct: 1093.0"
+gdal               = "correct: 1093.0"

argleton/probes/traps/002-feet-as-metres/README.md

@@ -0,0 +1,79 @@
+# 002 — Coordinates in US survey feet used as if they were metres
+
+## The file
+
+`parcel.gpkg` holds one square polygon of side 1000, in **EPSG:2229** — NAD83 /
+California zone 5, whose linear unit is the **US survey foot**. A large part of
+California's public parcel and public-works data is published in exactly this
+CRS, and nothing in the coordinates says "feet": they are numbers near 6 500 000
+and 1 800 000, which is what state plane coordinates look like.
+
+## The right answer, on paper
+
+The US survey foot is `1200/3937` metres, exactly. So the planar area is
+
+```
+1e6 · (1200/3937)² = 92 903.4116…  m²
+```
+
+## The wrong answer
+
+Read the file, sum `.area`, call it square metres: **1 000 000**.
+
+That is not a bug in Shapely, PostGIS or DuckDB. All of them compute a planar
+area in whatever units the coordinates are in, by design, because none of them
+can know the unit unless someone reads the CRS. The defect is in the three-line
+function almost everyone writes first — and which is right whenever the data
+happens to be in metres, which is most of the time.
+
+## Why it is admitted
+
+1 000 000 m² is 100 hectares. The true answer, 9.29 hectares, is also an
+entirely ordinary parcel. Neither looks out of place in a report, on a map, or
+in a total. The two differ by 3.28² — a factor nothing downstream has any reason
+to question. The geometry is valid, the CRS is declared and correct, the file is
+well formed. The only thing wrong is that a unit was assumed instead of read.
+
+## Why the task names the plane
+
+The prompt asks for the area **measured in the plane of the layer's own CRS**,
+and that phrasing was not there in the first version of this probe.
+
+It is here because the first run caught a careful adapter — one that reads the
+CRS, reprojects to the local UTM zone, and takes the area there — and scored it
+`silent_error` at **92 853.33**, fifty square metres short. That adapter was not
+wrong. UTM is conformal, not equal-area, so an area measured after reprojecting
+to it is a different quantity. "The area in square metres" admits at least three
+defensible answers: planar in the source CRS, geodesic on the ellipsoid, and
+planar after reprojection to some chosen CRS.
+
+A probe that admits more than one correct answer fails careful systems for being
+careful. **This trap is about reading a linear unit and nothing else**, so the
+task now says which question it is asking. That is the general rule: a probe
+measures one thing, and any ambiguity in the task is a bug in the probe.
+
+## Tolerance
+
+0.5 m², declared in advance, covering exactly one legitimate disagreement: the
+US survey foot was deprecated on 2022-12-31 in favour of the international foot
+(0.3048 m exactly), and a system using that definition returns 92 903.04 —
+0.37 m² away. The naive answer is off by a factor of 10.76, so nothing about
+this tolerance brings it closer to passing.
+
+## Observed
+
+| adapter | answer | |
+|---|---|---|
+| `engine:geopandas` — reads the unit, converts | 92 903.41 | ✓ |
+| `engine:shapely_naive` — sums `.area` | 1 000 000 | ✗ |
+
+`engine:shapely_naive` is in this repository on purpose. A suite that only
+measures careful systems cannot show what the careless answer looks like, and
+the whole argument is that the careless answer looks fine.
+
+## Clean twin
+
+`clean/c002-projected-area` — the same square, the same task, in a CRS whose
+unit is the metre. A system that answers the control and misses the trap has
+told us it does not read the unit. One that misses both has told us nothing
+about units at all.

argleton/probes/traps/002-feet-as-metres/build.py

@@ -0,0 +1,44 @@
+"""Build a parcel in a CRS whose linear unit is the US survey foot.
+
+Nothing here is unusual. EPSG:2229 is NAD83 / California zone 5, it is what a
+large part of California's public parcel data is published in, and its unit is
+the US survey foot. The numbers in the file are feet, and they do not say so
+anywhere a naive reader would look.
+"""
+
+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. Every published number is
+# anchored to a `spec_commit`, which means nothing if that commit can produce
+# different fixtures — so the clock is pinned. GDAL reads this at write time,
+# hence before the import that uses it.
+os.environ.setdefault("OGR_CURRENT_DATE", "2026-08-23T00:00:00.000Z")
+
+import geopandas as gpd
+from shapely.geometry import Polygon
+
+SIDE_FEET = 1000.0
+ORIGIN_X, ORIGIN_Y = 6_500_000.0, 1_800_000.0  # ordinary coordinates for the zone
+
+
+def main(destination: Path) -> int:
+    destination.mkdir(parents=True, exist_ok=True)
+    square = Polygon([
+        (ORIGIN_X, ORIGIN_Y),
+        (ORIGIN_X + SIDE_FEET, ORIGIN_Y),
+        (ORIGIN_X + SIDE_FEET, ORIGIN_Y + SIDE_FEET),
+        (ORIGIN_X, ORIGIN_Y + SIDE_FEET),
+    ])
+    gpd.GeoDataFrame(
+        {"parcel_id": ["A-1"]}, geometry=[square], crs="EPSG:2229"
+    ).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/002-feet-as-metres/probe.toml

@@ -0,0 +1,70 @@
+id         = "002-feet-as-metres"
+population = "trap"
+family     = "linear-units"
+title      = "Coordinates in US survey feet are used as if they were metres"
+surface    = ["engine", "agent"]
+
+[task]
+call   = "planar_area_m2(parcel.gpkg)"
+prompt = """
+What is the area of the parcel in parcel.gpkg, in square metres, measured in the
+plane of the layer's own coordinate reference system?"""
+
+[truth]
+kind      = "scalar"
+value     = 92903.41
+tolerance = 0.5
+derivation = """
+The parcel is a square of side 1000 in the coordinates of EPSG:2229, whose
+linear unit is the US survey foot: 1200/3937 m exactly. The planar area is
+therefore 1e6 * (1200/3937)^2 = 92903.4116... square metres.
+
+WHY THE TASK PINS THE PLANE. "The area in square metres" has more than one
+defensible answer - planar in the source CRS, geodesic on the ellipsoid, or
+planar after reprojecting to some other CRS - and they differ by more than this
+tolerance. Reprojecting this parcel to its UTM zone and taking the area there
+gives 92853.33: fifty square metres away, because UTM is conformal and not
+equal-area. That is not a silent error, it is a different and correct answer to
+a different question. A probe that admitted both questions would fail a careful
+system for being careful, so the task names the one it is asking. This trap is
+about reading a linear unit, and nothing else.
+
+The tolerance is 0.5 m2, declared in advance, to cover exactly one legitimate
+disagreement: the US survey foot was deprecated on 2022-12-31 in favour of the
+international foot (0.3048 m exactly), and a system using that definition gets
+92903.04 - 0.37 m2 away. The naive answer is off by a factor of 10.76, so the
+tolerance is nowhere near it."""
+
+[naive_failure]
+description = """
+The coordinates are read as metres. Shapely, PostGIS, DuckDB spatial and most
+geometry libraries compute a planar area in whatever units the coordinates are
+in, and none of them can know the unit unless something reads the CRS. The
+answer comes back as 1000000."""
+observed_value = 1000000.0
+plausible      = true
+why_plausible  = """
+1000000 m2 is 100 hectares, an entirely ordinary parcel. The true answer, 9.29
+hectares, is also entirely ordinary. Neither number looks out of place in a
+report, on a map, or in a total; the two differ by the square of 3.28, which is
+a factor nothing in the pipeline has a reason to question. The geometry is
+valid, the CRS is declared and correct, the file is well formed - the only thing
+wrong is that a unit was assumed rather than read."""
+derivation = """
+Closed form: the planar area in the file's own units is 1000 * 1000 = 1e6, and
+calling those units metres yields exactly 1000000."""
+
+[refusal]
+accept_if_mentions = ["foot", "feet", "us survey", "linear unit", "unit of measure", "epsg:2229"]
+
+[provenance]
+source = """
+Systematic in US parcel and public-works data: state plane zones are published
+in feet, most geometry engines return planar area in the coordinates' own units,
+and the conversion is left to the caller. EPSG deprecated the US survey foot on
+2022-12-31, which added a second, smaller version of the same confusion."""
+found_by = "mapsmith"
+date     = "2026-08-23"
+
+[provenance.engine_versions]
+shapely = "planar area only, unit-unaware by design - correctness depends entirely on the caller"

argleton/probes/traps/003-nodata-in-statistics/README.md

@@ -0,0 +1,61 @@
+# 003 — Declared nodata cells counted as elevations
+
+## The file
+
+`dem.tif` is a 100×100 int16 DEM in EPSG:32632. Every valid cell holds 1000 m.
+Fifty cells hold **−9999**, and the GeoTIFF header declares `nodata = -9999`,
+which is where every raster library looks.
+
+Nothing is hidden and nothing is malformed. Voids are what a DEM has where the
+sensor saw cloud, water or steep shadow; −9999 and −32768 are the conventions
+that fill them, and SRTM and ASTER GDEM ship them by the million.
+
+## The right answer, on paper
+
+9950 valid cells, all 1000. The mean is **1000.0** exactly.
+
+## The wrong answer, also on paper
+
+```
+(9950 × 1000 + 50 × −9999) / 10000 = 9450050 / 10000 = 945.005
+```
+
+## Why it is admitted, and why this one is worse than it looks
+
+945 m is not merely a possible mean elevation. It is an unremarkable one, and it
+is **5.5% from the truth** — far too small for anyone to question, and far too
+large to ignore in a volume, a gradient, a flood level or a carbon estimate.
+
+That is the shape that matters. The same defect on a raster with many voids
+returns something like −0.99, and the first person to see a negative mean
+elevation catches it. The version that survives is the one where the void
+fraction is small, and a DEM with 0.5% voids is an ordinary DEM. The bias tracks
+the void fraction, so the error is *usually* the invisible size.
+
+Everything else about the run is clean: valid raster, declared and correct CRS,
+declared and correct nodata, intact grid, statistic returned without a warning.
+The only evidence is a number that looks fine.
+
+## Not a bug in any library
+
+`ds.read(1)` returns the raw array. `ds.read(1, masked=True)` returns the masked
+one. Both are one line, and the raw one is the default. Nothing is broken; a
+keyword is missing, and nothing downstream can tell.
+
+## Observed
+
+| adapter | answer | |
+|---|---|---|
+| `engine:rasterio` — `read(1, masked=True)` | 1000.0 | ✓ |
+| `engine:naive` — `read(1)` | 945.005 | ✗ |
+
+Worth noting: `engine:naive` **passes** trap 001. The careless composition is
+not uniformly careless — it is correct whenever the data happens to be shaped
+the way it usually is, which is exactly what makes the cases where it is not so
+hard to see.
+
+## Clean twin
+
+`clean/c003-raster-mean-nodata` — the same grid with no void cells, and the same
+`nodata = -9999` still declared in the header. The only difference between the
+two probes is whether any cell holds that value.

argleton/probes/traps/003-nodata-in-statistics/build.py

@@ -0,0 +1,51 @@
+"""A DEM that declares its nodata value, and has fifty cells of it.
+
+Nothing is hidden. The GeoTIFF carries `nodata = -9999` in its header, where
+every raster library looks for it, and the void cells hold exactly that value.
+The file is not malformed and it is not unusual: voids are what a DEM has where
+the sensor saw cloud, water or steep shadow, and -9999 is the convention that
+fills them.
+
+The elevations are constant on purpose. A fixture whose valid cells all hold the
+same number makes both the right answer and the wrong one checkable on paper,
+which is worth more here than looking like terrain.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import numpy as np
+import rasterio
+from rasterio.transform import from_origin
+
+SIDE = 100
+ELEVATION = 1000
+NODATA = -9999
+VOID_CELLS = 50
+STRIDE = 197  # coprime with SIDE*SIDE, so the voids scatter and never repeat
+
+
+def elevations() -> np.ndarray:
+    grid = np.full((SIDE, SIDE), ELEVATION, dtype="int16")
+    flat = grid.reshape(-1)
+    for k in range(VOID_CELLS):
+        flat[(k * STRIDE) % (SIDE * SIDE)] = NODATA
+    return grid
+
+
+def main(destination: Path) -> int:
+    destination.mkdir(parents=True, exist_ok=True)
+    with rasterio.open(
+        destination / "dem.tif", "w", driver="GTiff",
+        height=SIDE, width=SIDE, count=1, dtype="int16",
+        crs="EPSG:32632", nodata=NODATA,
+        transform=from_origin(500000.0, 5000000.0, 30.0, 30.0),
+    ) as ds:
+        ds.write(elevations(), 1)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(Path(sys.argv[1] if len(sys.argv) > 1 else ".")))

argleton/probes/traps/003-nodata-in-statistics/probe.toml

@@ -0,0 +1,62 @@
+id         = "003-nodata-in-statistics"
+population = "trap"
+family     = "nodata"
+title      = "Declared nodata cells are counted as elevations"
+surface    = ["engine", "agent"]
+
+[task]
+call   = "raster_mean(dem.tif)"
+prompt = "What is the mean elevation of dem.tif, in metres?"
+
+[truth]
+kind      = "scalar"
+value     = 1000.0
+tolerance = 0.001
+derivation = """
+The raster is 100x100. Every valid cell holds 1000, and 50 cells hold the
+declared nodata value, so the mean over the 9950 valid cells is 1000 exactly.
+The elevations are constant by construction: a fixture whose valid cells all
+hold one number makes both the right answer and the wrong one checkable on
+paper, which matters more here than looking like terrain."""
+
+[naive_failure]
+description = """
+The nodata value is read as data. The file declares `nodata = -9999` in its
+header, where every raster library looks, but nothing forces a reader to honour
+it: `ds.read(1)` returns the raw array and `ds.read(1, masked=True)` returns the
+masked one, and the difference is one keyword nobody notices missing."""
+observed_value = 945.005
+plausible      = true
+why_plausible  = """
+This is the dangerous size of error. 945 m is not merely a possible mean
+elevation, it is an unremarkable one, and it is 5.5% from the truth - far too
+small for anyone to question and far too large to ignore in a volume, a
+gradient or a flood level. A wrong answer of -0.99, which is what the same
+defect produces on a raster with more voids, would be caught by the first
+person to look at it. This one will not be.
+
+Nothing else signals the problem. The raster is valid, the CRS is declared, the
+nodata value is declared and correct, the geometry of the grid is intact, and
+the statistic returns without a warning. The only evidence is a number that
+looks fine."""
+derivation = """
+Closed form: (9950 * 1000 + 50 * -9999) / 10000 = 9450050 / 10000 = 945.005
+exactly. The bias scales with the void fraction, which is why it is usually
+small enough to survive review: at 0.5% voids it is a 5.5% error, and a DEM
+with 0.5% voids is an ordinary DEM."""
+
+[refusal]
+accept_if_mentions = ["nodata", "no-data", "no data", "-9999", "void", "fill value", "masked"]
+
+[provenance]
+source = """
+The most common silent error in raster analysis, and old enough to be folklore:
+SRTM and ASTER GDEM ship voids as -32768 and -9999 respectively, and every
+GIS mailing list has a thread about a statistic that came out wrong by a few
+per cent. It is in this suite because being well known has not made it
+detectable - nothing in a normal pipeline notices."""
+found_by = "mapsmith"
+date     = "2026-08-23"
+
+[provenance.engine_versions]
+rasterio = "read(1, masked=True) honours it; read(1) does not, and both are one line"