gap: the water-levels note points at `hidden_tiles`, which does not exist #244

New issue

Closed

opened 2026-08-31 01:44:45 +00:00 by viberfox-agent · 0 comments

viberfox-agent commented

2026-08-31 01:44:45 +00:00

Collaborator

Found while QA-ing what #197 shipped (#243).

What I did

#197 landed as documentation only: docs/notes/rijkswaterstaat-water-levels.md, plus a
docs/direction.md row moved from "frontier" to "checked and not taken". So the deliverable
a reader meets is the note, and its most actionable part is the closing section "What would
have to exist before this is revisited" — the two things that would reopen the question.

I followed step 1 of that section the way a future reader would, by grepping for the symbol it names.

What happened

Step 1 reads:

A hole in the clipmap under water polygons. hidden_tiles
(map_stream.rs:884) hides a tile only when finer ready tiles paint over it
completely; nothing subtracts geometry.

There is no hidden_tiles in this repository. The only occurrence of the string anywhere in
the tree is that line of the note itself:

$ grep -rn "hidden_tiles" --include=*.rs --include=*.md .
docs/notes/rijkswaterstaat-water-levels.md:153

It is not drift from a later rename either — the symbol did not exist at the note's own commit
(004d9b0). The function that does what the sentence describes is occluded_by_finer, and
it was already called that on that same commit:

$ git show 004d9b0:crates/cartopolis/src/systems/map/map_stream.rs | grep -n occluded_by_finer
250:    /// [`occluded_by_finer`]. Written by [`update_tile_occlusion`], read by
903:fn occluded_by_finer(
958:    let occluded = occluded_by_finer(&live, finest, MIN_ZOOM);

The prose is accurate — occluded_by_finer does hide a tile only when finer ready tiles cover
its footprint, and nothing subtracts geometry — and the :884 line reference still lands inside
that function's doc comment. Only the name is wrong.

What a reader would expect instead

The whole point of a "checked and not taken" note is that the check is not repeated, and this is
the one paragraph written for somebody who wants to undo the decision. They grep the symbol,
get zero hits, and have to re-derive where clipmap occlusion lives before they can judge how big
step 1 is. Everything else in the note is precise to the byte (I reproduced the catalogue size,
the station counts, the distance table and the AHN anchor probe exactly), which makes this the
one place it sends a reader to something that isn't there.

Where the seam is

docs/notes/rijkswaterstaat-water-levels.md:153 — hidden_tiles → occluded_by_finer
crates/cartopolis/src/systems/map/map_stream.rs — fn occluded_by_finer, and
update_tile_occlusion, which is what actually applies the result

A one-word documentation fix. Filed rather than fixed because #243 is a QA pass and says to change
no code on that ticket.

Found while QA-ing what #197 shipped (#243). ## What I did #197 landed as documentation only: `docs/notes/rijkswaterstaat-water-levels.md`, plus a `docs/direction.md` row moved from "frontier" to "checked and not taken". So the deliverable a reader meets is the note, and its most actionable part is the closing section **"What would have to exist before this is revisited"** — the two things that would reopen the question. I followed step 1 of that section the way a future reader would, by grepping for the symbol it names. ## What happened Step 1 reads: > 1. **A hole in the clipmap under water polygons.** `hidden_tiles` > (`map_stream.rs:884`) hides a tile only when finer ready tiles paint over it > completely; nothing subtracts geometry. There is no `hidden_tiles` in this repository. The only occurrence of the string anywhere in the tree is that line of the note itself: ``` $ grep -rn "hidden_tiles" --include=*.rs --include=*.md . docs/notes/rijkswaterstaat-water-levels.md:153 ``` It is not drift from a later rename either — the symbol did not exist at the note's own commit (`004d9b0`). The function that does what the sentence describes is **`occluded_by_finer`**, and it was already called that on that same commit: ``` $ git show 004d9b0:crates/cartopolis/src/systems/map/map_stream.rs | grep -n occluded_by_finer 250: /// [`occluded_by_finer`]. Written by [`update_tile_occlusion`], read by 903:fn occluded_by_finer( 958: let occluded = occluded_by_finer(&live, finest, MIN_ZOOM); ``` The *prose* is accurate — `occluded_by_finer` does hide a tile only when finer ready tiles cover its footprint, and nothing subtracts geometry — and the `:884` line reference still lands inside that function's doc comment. Only the name is wrong. ## What a reader would expect instead The whole point of a "checked and not taken" note is that the check is not repeated, and this is the one paragraph written for somebody who wants to *undo* the decision. They grep the symbol, get zero hits, and have to re-derive where clipmap occlusion lives before they can judge how big step 1 is. Everything else in the note is precise to the byte (I reproduced the catalogue size, the station counts, the distance table and the AHN anchor probe exactly), which makes this the one place it sends a reader to something that isn't there. ## Where the seam is - `docs/notes/rijkswaterstaat-water-levels.md:153` — `hidden_tiles` → `occluded_by_finer` - `crates/cartopolis/src/systems/map/map_stream.rs` — `fn occluded_by_finer`, and `update_tile_occlusion`, which is what actually applies the result A one-word documentation fix. Filed rather than fixed because #243 is a QA pass and says to change no code on that ticket.

viberfox-agent added this to the Viberfox project

2026-08-31 01:44:50 +00:00

viberfox-agent added the

qa-gap

label

2026-08-31 01:44:51 +00:00

viberfox-agent referenced this issue

2026-08-31 01:45:40 +00:00

QA: what #197 shipped — Rijkswaterstaat water levels: is it worth wiring in? #243

viberfox-agent referenced this issue

2026-08-31 02:38:46 +00:00

gap: the tile-fixture path in two notes moved to crates/geo and was never updated #248