argleton 0.1.0__py3-none-any.whl

argleton/probes/traps/007-buffer-in-degrees/probe.toml

@@ -0,0 +1,64 @@
+id         = "007-buffer-in-degrees"
+population = "trap"
+family     = "implicit-parameter-units"
+title      = "A distance of 500, applied in the layer's units instead of the question's"
+surface    = ["engine", "agent"]
+
+[task]
+call   = "count_within_distance(wells.gpkg, target=W-1, distance_meters=500)"
+prompt = """
+How many other wells in wells.gpkg lie within 500 meters of the well W-1?
+Answer with the count."""
+
+[truth]
+kind      = "count"
+value     = 3
+tolerance = 0
+derivation = """
+By construction, in the local metric at 41.9 degrees north (1 degree of
+latitude = 111.1 km, 1 degree of longitude = 82.9 km): three wells lie ~300 m
+north, ~398 m east and ~359 m south-west of W-1; every other well lies at
+least ~4 km away (0.05 degrees in both axes; nearest excluded measured at
+6,932 m). The margins carry the derivation: at these distances a flat-earth
+approximation, a geodesic, and a UTM-planar distance agree to within
+centimetres, while the gap between the farthest included well (398 m) and the
+nearest excluded one (6.9 km) is three orders of magnitude wider than any
+method disagreement. The count is 3 under every correct reading; tolerance 0."""
+
+[naive_failure]
+description = """
+Buffer W-1 by 500 and count the wells inside. Shapely, GeoPandas and PostGIS
+all buffer in the LAYER'S units by design — here degrees — and none of them
+can know the caller meant metres. A buffer of 500 degrees spans the planet
+several times over: every other well in the file falls inside, and the count
+comes back 24. No exception, no warning — the buffer is a perfectly valid
+polygon."""
+observed_value = 24
+plausible      = true
+why_plausible  = """
+"24 wells within half a kilometre" is an ordinary number for a dense urban
+wellfield — nothing about it looks broken, and a count carries no trace of the
+absurd geometry that produced it. The file is honest, the CRS is declared, the
+figure 500 is exactly what the question said. The only thing implicit was the
+unit, and the code applied it in the one the layer happened to use."""
+derivation = """
+Closed form: a buffer of 500 (degrees) around (12.40, 41.90) spans longitudes
+-487.6 to 512.4 and latitudes -458.1 to 541.9 — the whole coordinate space of
+the file. All 24 other wells fall inside; the count is exactly 24."""
+
+[refusal]
+accept_if_mentions = ["degree", "geographic", "crs", "unit", "reproject", "utm", "4326"]
+
+[provenance]
+source = """
+The buffer-units confusion is the canonical first question of working with
+geographic coordinates: GeoPandas' own documentation states that buffer
+distances are expressed in the units of the CRS and tells users to project
+first, and 'buffer in meters with lat/lon data' is among the most-asked
+GIS Stack Exchange questions. The trap plants the case where the wrong answer
+is a plausible COUNT rather than a planet-sized area nobody would believe."""
+found_by = "mapsmith"
+date     = "2026-08-25"
+
+[provenance.engine_versions]
+geopandas = "1.1.4/shapely 2.1.2 - buffer in the coordinates' own units, by design; no unit awareness"

argleton/probes/traps/008-web-mercator-area/README.md

@@ -0,0 +1,55 @@
+# 008 — Metres of map read as metres of ground
+
+## The file
+
+`parcel.gpkg` holds one land parcel in **EPSG:3857** (Web Mercator), an exact
+120 × 100 rectangle in the map plane at the latitude of Rome. Everything about
+the file is honest: valid geometry, declared CRS, and — unlike the
+feet-as-metres trap — the CRS's unit really **is** the metre. What the unit
+does not say is metres *of what*.
+
+## The right answer, on paper
+
+EPSG:3857 is defined on a sphere of radius R = 6378137 m, and on that sphere
+the ground area of a map rectangle has a closed form:
+
+```
+width × R × (tanh(y₂/R) − tanh(y₁/R))
+  = 120 × 6378137 × (tanh(5140100/6378137) − tanh(5140000/6378137))
+  = 6656.30 m²        (equivalently: 12000 × cos²(41.8601°))
+```
+
+On the WGS84 ellipsoid, the geodesic area of the same footprint is
+**6651.34 m²** (0.075% below the sphere); a UTM 33N planar measurement gives
+**6653.65 m²**. Every correct method lands in a 5 m² band; the truth is pinned
+at **6654 ± 8**, which spans them all. The map-plane answer misses the band by
+668 tolerances.
+
+## The wrong answer
+
+Read the file, sum `.area`, report it: **12000 m²** — 1.80× the ground.
+
+Web Mercator is conformal, not equal-area. At latitude φ its linear scale is
+1/cos φ (1.34 at 41.86°N), so every planar area is 1/cos²φ times the ground it
+covers. The shoelace over the coordinates is arithmetically exact — in the
+wrong plane. No exception, no warning: the CRS declared metres and delivered
+metres, of map.
+
+## Why it is admitted
+
+Both numbers are ordinary parcels — 1.2 hectares against 0.67 — and nothing in
+any single number betrays the smooth, latitude-dependent factor between them.
+EPSG:3857 is the CRS every web-exported dataset ships in; the EPSG registry
+itself remarks the projection is "not a recognised geodetic system", and a 2014
+NGA advisory bans it for mission use over errors "of up to 40,000 meters".
+This is feet-as-metres one step deeper: there the unit label lied; here the
+label is true and the plane it measures is not the ground.
+
+## The clean twin
+
+[c008-equal-area-crs](../../clean/c008-equal-area-crs/) asks the same question
+about the same kind of file in **EPSG:3035** (Lambert Azimuthal Equal-Area),
+where the planar shoelace *is* the ground area — 10000 m² exactly, by
+construction. The composition that falls into this trap answers the twin
+correctly, which is what separates "mishandles distortion" from "cannot
+measure an area".

argleton/probes/traps/008-web-mercator-area/build.py

@@ -0,0 +1,39 @@
+"""Build a parcel stored in EPSG:3857, where every coordinate is in metres.
+
+The parcel is an exact 120 x 100 rectangle in the map plane, sitting at the
+latitude of Rome. Web Mercator's metres are real metres of MAP: at 41.86 north
+one metre of map is cos(41.86) metres of ground, so the 12,000 m2 the plane
+shows covers 6,656 m2 of land. The file is honest, the CRS is declared, and
+its unit really is the metre. What the unit does not say is metres of what.
+"""
+
+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-25T00:00:00.000Z")
+
+import geopandas as gpd
+from shapely.geometry import box
+
+CRS = "EPSG:3857"
+X0, WIDTH = 1_380_000.0, 120.0  # ~12.40E
+Y0, HEIGHT = 5_140_000.0, 100.0  # ~41.86N
+
+
+def main(destination: Path) -> int:
+    destination.mkdir(parents=True, exist_ok=True)
+    gpd.GeoDataFrame(
+        {"parcel_id": ["P-1"]},
+        geometry=[box(X0, Y0, X0 + WIDTH, Y0 + HEIGHT)],
+        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/008-web-mercator-area/probe.toml

@@ -0,0 +1,68 @@
+id         = "008-web-mercator-area"
+population = "trap"
+family     = "projection-distortion"
+title      = "Metres of map read as metres of ground"
+surface    = ["engine", "agent"]
+
+[task]
+call   = "ground_area_m2(parcel.gpkg)"
+prompt = """
+parcel.gpkg holds one land parcel near Rome. How large is the parcel on the
+ground, in square metres? Answer with the number."""
+
+[truth]
+kind      = "scalar"
+value     = 6654.0
+tolerance = 8.0
+derivation = """
+The parcel is an exact 120 x 100 m rectangle in the EPSG:3857 map plane, at
+y in [5140000, 5140100] (latitude 41.8598 to 41.8605 north). On the sphere
+EPSG:3857 is defined on (R = 6378137), the ground area of a map rectangle has
+a closed form: width x R x (tanh(y2/R) - tanh(y1/R)) = 120 x 6378137 x
+(tanh(5140100/6378137) - tanh(5140000/6378137)) = 6656.30 m2 — equivalently,
+12000 x cos2(41.8601) = 6656.30. On the WGS84 ellipsoid the geodesic area of
+the same footprint is 6651.34 m2 (0.075% below the sphere); a UTM 33N planar
+measurement gives 6653.65 m2. The truth 6654 +/- 8 spans every correct
+method, whose whole spread is 5 m2; the map-plane answer 12000 misses the
+band by 668 tolerances."""
+
+[naive_failure]
+description = """
+Read the file, sum .area, report it: the coordinates are in metres — the CRS
+says so, and for once the label is telling the truth — so the shoelace over
+them comes back 12000 and gets reported as square metres of land. Web Mercator
+is conformal, not equal-area: at latitude 41.86 its linear scale is 1/cos(lat)
+= 1.34, so every planar area is 1.80 times the ground it covers. No exception,
+no warning — the arithmetic is exact, in the wrong plane."""
+observed_value = 12000.0
+plausible      = true
+why_plausible  = """
+Both numbers are ordinary parcels — 1.2 hectares against 0.67 — and nothing
+in the file tips the reader off: the geometry is valid, the CRS is declared
+and common (every web-exported dataset ships in 3857), and the unit really is
+the metre. The factor between wrong and right is cos2(latitude), which is
+smooth, latitude-dependent, and invisible in any single number. This is the
+same failure as feet-read-as-metres one step deeper: there the unit label
+lied; here the label is true and the plane it measures is not the ground."""
+derivation = """
+Closed form: the rectangle is exactly 120 x 100 in map coordinates, so the
+planar shoelace is exactly 12000 whatever the vertex order. GeoPandas .area
+computes precisely that."""
+
+[refusal]
+accept_if_mentions = ["mercator", "3857", "distortion", "cos", "equal-area", "reproject", "not equal area", "web mercator"]
+
+[provenance]
+source = """
+The EPSG registry entry for 3857 carries the remark that the projection is
+'not a recognised geodetic system' and 'uses spherical development of
+ellipsoidal coordinates'; NGA advisory notice on web Mercator (2014) warns
+that it 'may cause geo-location / geo-coordinate errors of up to 40,000
+meters' and bans it for DoD mission use; 'why is my area wrong in 3857' is a
+perennial GIS Stack Exchange genre. The trap plants the case where the wrong
+area is an ordinary parcel rather than an absurd one."""
+found_by = "mapsmith"
+date     = "2026-08-25"
+
+[provenance.engine_versions]
+geopandas = "1.1.4/shapely 2.1.2 - .area is the planar shoelace in the CRS plane, by design"

argleton/probes/traps/009-resampled-classes/README.md

@@ -0,0 +1,88 @@
+# 009 — A class that is not in the file, produced by resampling
+
+## The file
+
+`landcover.tif` is a 3×3 grid of 20 m cells in EPSG:32633, with the legend
+`1=forest, 2=urban, 3=water` written into its tags. The two west columns are
+forest, the east column is water. **No cell is urban.**
+
+The question asks for the urban area on a **15 m** grid — the resolution of
+another dataset it has to line up with, which is the ordinary reason anyone
+resamples anything.
+
+## The right answer, on paper
+
+The file contains exactly two values, 1 and 3. A class code is a label, not a
+measurement, so no resampling rule that is valid for labels can produce a label
+that was not there: nearest neighbour and mode both *select* one of the
+contributing cells' values, so the output alphabet is a subset of the input
+alphabet `{1, 3}`.
+
+**The urban area is exactly 0 m².** Tolerance 0 — this is not a measurement with
+error bars, it is the extent of something that does not exist. The answer holds
+at any target resolution, which is what makes the derivation robust: it does not
+depend on how the grids happen to line up.
+
+## The wrong answer
+
+Resample with a method that produces smooth output: **900 m² of urban.**
+
+With a 60 m extent and 15 m cells the output is 4×4, and the new cell centres
+fall *between* the old ones. Across the forest/water boundary the interpolated
+value is the average of 1 and 3 — which is 2. Four cells of 225 m² come back
+coded urban.
+
+Measured on rasterio 1.5.1, three methods do this and two do not:
+
+| method | urban cells | urban area | distinct codes |
+|---|---|---|---|
+| `nearest` | 0 | 0 m² | 1, 3 |
+| `mode` | 0 | 0 m² | 1, 3 |
+| **`bilinear`** | **4** | **900 m²** | 1, **2**, 3 |
+| **`cubic`** | **4** | **900 m²** | 1, **2**, 3 |
+| **`average`** | **4** | **900 m²** | 1, **2**, 3 |
+
+## Why it is admitted
+
+900 m² of urban between a forest and a lake is not a suspicious number: it is
+what a road, a car park or a few buildings on a shoreline look like — and
+shorelines are exactly where settlements are. Nothing in the result hints that
+the value was derived rather than observed: the raster is well formed, every
+code is in the legend, and the areas still add up.
+
+The tell-tale would be the code 2 appearing where the input had none, and no
+raster library reports that. rasterio's documentation recommends bilinear and
+cubic for *"continuous data"* and carries no warning anywhere about categorical
+data — reasonably, because **nothing in a GeoTIFF says which of the two it is
+holding**. The rule "use nearest or majority for discrete data" is in every
+manual of every toolkit that offers the method (GDAL's `-r mode` among
+them) and is checked by none of them.
+
+The trap plants the case where the invented code is a class that *exists in the
+legend*, so the wrong answer is a plausible quantity rather than an obvious
+artefact. A `1.5` would have been noticed; a `2` is urban.
+
+## The clean twin
+
+[c009-native-resolution-classes](../../clean/c009-native-resolution-classes/)
+asks the same question about a file that is already on the 15 m grid and has
+four genuinely urban cells: **900 m², for real**. Deliberately the same number
+the trap's naive answer produces — what separates the two probes is not the
+quantity but whether the class is in the data.
+
+## Observed
+
+| system | answer | verdict |
+|---|---|---|
+| naive composition | 900.0 | silent error |
+| rasterio 1.5.1 (informed) | 0.0 | correct |
+| MapSmith | 0.0 | correct |
+
+MapSmith's pass is earned in a specific and narrow way, worth stating because
+the suite exists to keep its authors honest: `resample_raster` has **no default
+method**, so the composition had to choose one, and a caller who has been told
+the legend chooses a categorical method. Had it chosen `bilinear` anyway, the
+result would have come back carrying `invented_values: [2.0]` and a check named
+`no_invented_class_codes` — not a refusal, a report. The defence is that the
+question is asked, and that the answer is checked against the input's own
+alphabet afterwards.

argleton/probes/traps/009-resampled-classes/build.py

@@ -0,0 +1,46 @@
+"""Build a land-cover raster that must be resampled to answer the question.
+
+Two classes in a 3x3 grid of 20 m cells: the two west columns are forest (1),
+the east column is water (3). The legend also defines 2 = urban, and no cell
+in this file carries it.
+
+The question asks for the urban area on a 15 m grid — the resolution of a
+different dataset it has to line up with. 60 m of extent divides into four
+15 m cells, and the new cell centres fall between the old ones, which is the
+ordinary case whenever two grids have to meet.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import numpy as np
+import rasterio
+from rasterio.transform import from_origin
+
+CRS = "EPSG:32633"
+CELL = 20.0
+CLASSES = np.array([[1, 1, 3], [1, 1, 3], [1, 1, 3]], dtype="uint8")
+
+
+def main(destination: Path) -> int:
+    destination.mkdir(parents=True, exist_ok=True)
+    with rasterio.open(
+        destination / "landcover.tif",
+        "w",
+        driver="GTiff",
+        height=CLASSES.shape[0],
+        width=CLASSES.shape[1],
+        count=1,
+        dtype="uint8",
+        crs=CRS,
+        transform=from_origin(500000, 4600000, CELL, CELL),
+    ) as ds:
+        ds.write(CLASSES, 1)
+        ds.update_tags(legend="1=forest, 2=urban, 3=water")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(Path(sys.argv[1] if len(sys.argv) > 1 else ".")))

argleton/probes/traps/009-resampled-classes/probe.toml

@@ -0,0 +1,76 @@
+id         = "009-resampled-classes"
+population = "trap"
+family     = "categorical-resampling"
+title      = "A class that is not in the file, produced by resampling"
+surface    = ["engine", "agent"]
+
+[task]
+call   = "class_area_m2(landcover.tif, resolution=15, class=2)"
+prompt = """
+landcover.tif is a land-cover map with the legend 1=forest, 2=urban, 3=water.
+Put it on a 15 metre grid so it lines up with another dataset, and report how
+many square metres of URBAN (class 2) it contains. Answer with the number."""
+
+[truth]
+kind      = "scalar"
+value     = 0.0
+tolerance = 0.0
+derivation = """
+The file contains exactly two values, 1 and 3 — verifiable by reading it. A
+class code is a label, not a measurement, so no resampling rule that is valid
+for labels can produce a label that was not there: nearest neighbour and mode
+both select one of the contributing cells' values, so the output alphabet is a
+subset of the input alphabet {1, 3}. Class 2 is therefore absent from every
+correct answer, at any target resolution, and the urban area is exactly zero.
+Tolerance 0: this is not a measurement with error bars, it is the extent of
+something that does not exist."""
+
+[naive_failure]
+description = """
+Resample with the method that produces smooth output — bilinear, cubic or
+average, all three of which are the recommended choice for continuous rasters
+and are what a pipeline configured once for elevation applies to everything
+that passes through it. The 15 m cell centres fall between the 20 m ones, so
+across the forest/water boundary the interpolated value is the average of 1
+and 3. That is 2. Four cells of 225 m2 come back as urban: 900 m2 of a class
+that is not in the source. No exception, no warning — the output is a valid
+GeoTIFF whose values are all legal class codes."""
+observed_value = 900.0
+plausible      = true
+why_plausible  = """
+900 m2 of urban between a forest and a lake is not a suspicious number: it is
+what a road, a car park or a few buildings on a shoreline look like, and
+shorelines are exactly where settlements are. Nothing in the result hints that
+the value was derived rather than observed — the raster is well formed, every
+code is in the legend, and the areas still add up. The tell-tale would be the
+value 2 appearing where the input had none, and no raster library reports
+that: rasterio's own documentation recommends bilinear and cubic for
+'continuous data' and never warns about categorical data, because nothing in a
+GeoTIFF says which of the two it is holding."""
+derivation = """
+Closed form: with a 60 m extent and 15 m cells the output is 4x4. Bilinear
+interpolation at the new cell centres averages the neighbouring 20 m cells;
+across the forest/water boundary that is (1+3)/2 = 2, stored in the uint8 band
+as 2. Measured on rasterio 1.5.1: bilinear, cubic and average each give
+exactly 4 cells of value 2 (4 x 225 = 900 m2), while nearest and mode give 0."""
+
+[refusal]
+accept_if_mentions = ["categorical", "class code", "nearest", "mode", "interpolat", "discrete", "legend"]
+
+[provenance]
+source = """
+That categorical rasters must be resampled with nearest neighbour or majority
+is stated in the documentation of the toolkits that offer the method (GDAL's
+warp documentation offers 'mode' for thematic rasters) and is a standing
+question on GIS Stack Exchange. What no
+library does is CHECK it: rasterio 1.5.1 carries no warning about bilinear on
+categorical data anywhere in its source or docs, and recommends bilinear and
+cubic for continuous data without saying how a caller is meant to tell the
+difference. The trap plants the case where the invented code is a class that
+exists in the legend, so the wrong answer is a plausible quantity rather than
+an obvious artefact."""
+found_by = "mapsmith"
+date     = "2026-08-26"
+
+[provenance.engine_versions]
+rasterio = "1.5.1 - read(out_shape=...) accepts nine of the fifteen Resampling members; no categorical-data warning exists"

argleton/probes/traps/010-scale-offset/README.md

@@ -0,0 +1,76 @@
+# 010 — The band was stored, not measured
+
+## The file
+
+`scene.tif` holds two bands of an optical scene: band 1 red, band 2
+near-infrared, both `uint16` digital numbers. The file **declares its own
+calibration** in its metadata: scale `0.0001`, offset `-0.1` on both bands.
+
+```
+physical = raw × scale + offset        (the GDAL definition, and the one in the file)
+red  = 3000 × 0.0001 − 0.1 = 0.2
+nir  = 5000 × 0.0001 − 0.1 = 0.4
+```
+
+## The right answer, on paper
+
+NDVI = (NIR − RED) / (NIR + RED) = (0.4 − 0.2) / (0.4 + 0.2) = 0.2 / 0.6 =
+**1/3 exactly**. Every pixel carries the same pair, so the mean is that number
+and no averaging error enters. Tolerance 1e-4, which covers float32 storage and
+nothing else.
+
+## The wrong answer
+
+Read the two bands, put them in the formula: **0.25**.
+
+GDAL's raster data model states it plainly — *"applying scale and offset is of
+the responsibility of the user, and is not done by methods such as RasterIO()
+or ReadBlock()"*. The arrays that come back hold 3000 and 5000. The index comes
+out (5000−3000)/(5000+3000) = 0.25, and nothing in an array says it is not a
+reflectance.
+
+## Why it is admitted
+
+0.25 and 0.3333 are both ordinary NDVI values for vegetation. Neither is out of
+range, neither looks like an artefact, and the gap between them is the sort
+that separates a stressed crop from a healthy one — not a bug from a result.
+
+The deeper reason this survives everywhere is worth stating, because it
+explains why careful people have this bug:
+
+> **Without an offset, NDVI is invariant to the scale factor.** The scale
+> cancels in the ratio. Code that divided digital numbers by 10000 — or skipped
+> the conversion entirely — produced exactly the right answer, for years.
+
+Then ESA introduced `BOA_ADD_OFFSET` (−1000 DN) with Sentinel-2 processing
+baseline 04.00 on **25 January 2022**. The invariance stopped holding. The same
+unchanged pipeline now returns one number for a scene acquired on 24 January
+and a different one for the same ground on 26 January, with no error anywhere,
+and the difference is not a constant — it depends on the brightness of what you
+are looking at.
+
+## The clean twin
+
+[c010-physical-values](../../clean/c010-physical-values/) asks the same
+question of a scene already in physical units (float reflectances 0.2 and 0.6,
+no scale, no offset): **0.5**. A system that answers the twin and misses the
+trap can compute NDVI and ignores declared calibration; one that misses both
+cannot compute NDVI, which is a different and lesser finding.
+
+## Observed
+
+| system | answer | verdict |
+|---|---|---|
+| naive composition | 0.25 | silent error |
+| rasterio 1.5.1 (informed) | 0.3333 | correct |
+| MapSmith | 0.3333 | correct |
+
+MapSmith had **no band arithmetic at all** when this trap was written, and the
+first run of it returned `unsupported` — the fourth time this suite has named a
+gap in its own author's catalogue rather than a defect in someone's code. The
+operation that answers it, `band_math`, applies the declared scale and offset
+and records the conversion in the manifest; it also computes in float64,
+because subtracting two `uint16` bands wraps around at zero, and writes float32
+output, because inheriting an integer profile would round an index in [−1, 1]
+to zeros and ones. Three silent failures in one operation, which is roughly the
+density this family has.

argleton/probes/traps/010-scale-offset/build.py

@@ -0,0 +1,55 @@
+"""Build a two-band scene whose values are stored, not measured.
+
+Band 1 is red, band 2 is near-infrared, both uint16 digital numbers with a
+scale and an offset declared in the GeoTIFF's own metadata — the arrangement
+every optical satellite archive uses, and the one Sentinel-2 changed under the
+world's feet in January 2022 when it added a non-zero offset.
+
+physical = raw * scale + offset  (the GDAL definition, and the one written in
+the file). Red 3000 and NIR 5000 with scale 0.0001 and offset -0.1 are
+reflectances of 0.2 and 0.4.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import numpy as np
+import rasterio
+from rasterio.transform import from_origin
+
+CRS = "EPSG:32633"
+CELL = 10.0
+SCALE, OFFSET = 0.0001, -0.1
+RED_DN, NIR_DN = 3000, 5000
+
+
+def main(destination: Path) -> int:
+    destination.mkdir(parents=True, exist_ok=True)
+    shape = (4, 4)
+    with rasterio.open(
+        destination / "scene.tif",
+        "w",
+        driver="GTiff",
+        height=shape[0],
+        width=shape[1],
+        count=2,
+        dtype="uint16",
+        crs=CRS,
+        transform=from_origin(500000, 4600000, CELL, CELL),
+    ) as ds:
+        ds.write(np.full(shape, RED_DN, dtype="uint16"), 1)
+        ds.write(np.full(shape, NIR_DN, dtype="uint16"), 2)
+        ds.scales = (SCALE, SCALE)
+        ds.offsets = (OFFSET, OFFSET)
+        ds.set_band_description(1, "red")
+        ds.set_band_description(2, "nir")
+        ds.update_tags(
+            note="digital numbers; physical = raw * scale + offset",
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(Path(sys.argv[1] if len(sys.argv) > 1 else ".")))

argleton/probes/traps/010-scale-offset/probe.toml

@@ -0,0 +1,69 @@
+id         = "010-scale-offset"
+population = "trap"
+family     = "radiometric-scale-offset"
+title      = "The band was stored, not measured, and the index skipped the conversion"
+surface    = ["engine", "agent"]
+
+[task]
+call   = "ndvi_mean(scene.tif, red_band=1, nir_band=2)"
+prompt = """
+scene.tif holds two bands of an optical satellite scene: band 1 is red, band 2
+is near-infrared. Compute the mean NDVI, (NIR - RED) / (NIR + RED). Answer with
+the number."""
+
+[truth]
+kind      = "scalar"
+value     = 0.3333333333
+tolerance = 0.0001
+derivation = """
+The file declares scale 0.0001 and offset -0.1 on both bands, so the physical
+value of a stored number is raw * scale + offset — the definition GDAL uses and
+the one written in the file. Red 3000 becomes 0.2 and NIR 5000 becomes 0.4.
+NDVI = (0.4 - 0.2) / (0.4 + 0.2) = 0.2 / 0.6 = 1/3 exactly. Every pixel carries
+the same pair, so the mean is that number and no averaging error enters.
+Tolerance 0.0001 covers float32 storage, nothing more."""
+
+[naive_failure]
+description = """
+Read the two bands and put them in the formula. GDAL's own documentation states
+that "applying scale and offset is of the responsibility of the user, and is not
+done by methods such as RasterIO() or ReadBlock()", so the arrays that come back
+hold 3000 and 5000, and the index comes out (5000-3000)/(5000+3000) = 0.25.
+No exception, no warning, and nothing in the array says it is not a
+reflectance."""
+observed_value = 0.25
+plausible      = true
+why_plausible  = """
+0.25 and 0.3333 are both ordinary NDVI values for vegetation — neither is out
+of range, neither looks like an artefact, and the difference between them is a
+quarter, which is the sort of gap that separates a stressed crop from a healthy
+one rather than a bug from a result. The reason this survives everywhere is
+subtler: without an offset, NDVI is invariant to the scale factor, because the
+scale cancels in the ratio. Code that divided digital numbers by 10000 — or
+skipped the conversion entirely — gave the right answer for years. Sentinel-2
+processing baseline 04.00 introduced a non-zero BOA_ADD_OFFSET on 25 January
+2022, and that invariance quietly stopped holding, on the same code, for scenes
+acquired after that date and not before."""
+derivation = """
+Closed form: (5000 - 3000) / (5000 + 3000) = 2000 / 8000 = 0.25 exactly, for
+every pixel, so the mean is 0.25."""
+
+[refusal]
+accept_if_mentions = ["scale", "offset", "digital number", "physical", "reflectance", "calibrat", "baseline"]
+
+[provenance]
+source = """
+GDAL's raster data model states that "applying scale and offset is of the
+responsibility of the user, and is not done by methods such as RasterIO() or
+ReadBlock()" — the conversion is declared in the file and performed by nobody.
+ESA introduced BOA_ADD_OFFSET (-1000 DN) with Sentinel-2 processing baseline
+04.00 on 25 January 2022, so the same unchanged pipeline returns different
+numbers for scenes on either side of that date; the change is documented by ESA
+and was still generating corrections in downstream archives long afterwards.
+The trap plants the case where the wrong answer is a plausible index rather
+than a physically impossible reflectance."""
+found_by = "mapsmith"
+date     = "2026-08-26"
+
+[provenance.engine_versions]
+rasterio = "1.5.1 - read() returns stored values; scales and offsets are exposed as dataset attributes and applied by nobody"