#77: write down what a country has to look like, and audit the four we have #87

Merged

art merged 1 commit from issue-77-country-requirements into main

2026-08-09 10:46:27 +00:00

art-bot commented

2026-08-09 10:40:32 +00:00

Collaborator

Closes #77.

What this is

docs/country-requirements.md — 140 numbered requirements (R1…R140) describing what a
country in this map has to look like, with a check for each one, and an appendix recording
where the four current countries stood when it was written.

The document is built from three sources, in the order #77 asked for them:

How we do things today — the layer inventory, the shared contracts, the cascade, the
style invariants.
Every issue, open and closed — all 49 read, with the transferable rule extracted from
each. Bug reports filed against one country turned out to generalize far more often than
not; #64, #71, #29, #41 and #46 each yielded several requirements on their own.
The country docs and the per-country configs — passages that read as one country's
reasoning but state a project-wide rule.

MUST is a conformance requirement; SHOULD is a default a measurement may override, with
the measurement going in the country doc. Numbers are stable identifiers, not a reading
order, so a requirement added later never renumbers an existing one.

The stronger requirement #77 asked for

#77 said the capital should be the last name standing when every other name has generalized
away, and the top five names should be the five largest cities. That became R85, and it
is the requirement that did the most work: three of the four countries fail it.

country	z5 place labels	capital's rank
Iceland	`Ísland`	Reykjavík: not in the top 6, absent at z7
Poland	Białystok, Gdańsk, Katowice, Kielce	Warszawa: 15
Finland	FORSSA, HANKO, HEINOLA, HELSINKI	Helsinki: 4
Sweden	Stockholm, Göteborg, Västerås, Uppsala, Linköping, Malmö	Stockholm: 1

Iceland's is the sharp one. Its five highest-ranked places are Ísland (the country),
Kolbeinsey (an uninhabited skerry), Sundhnúkur (a crater row), 1000 manna hellir (a
cave) and ABC Garðurinn. conf/ismap.yaml's places reads the whole ornefni_punktar
toponym register and grades it by örnefnaflokkurkenni, which is a category code — land,
sea, water, ice — not a size signal: 44,530 names at importance 1, two at 2, one at 3. With
nothing to break ties the ranking falls straight to alphabetical.

The reason nobody saw it: Iceland is still served the legacy settlement_points layer
through the is tile source, and html/style.json draws both it and places from z4. The
real town names come from the legacy layer, which masks the broken one — and means every
Icelandic settlement is currently labelled twice.

Issues filed

Nine, #78–#86, one per non-conformance that did not already have an issue. Each cites the
requirement numbers it violates and carries the query that found it.

#78 Iceland's places ranks the toponym register, not settlements — and
settlement_points double-labels the map (R85, R86, R91)
#79 Poland's and Finland's place-name ladders go alphabetical at the top (R85, R87)
#80 Finland's place register ships its top tier in capitals, and duplicates it cased
(R94, R90)
#81 Finland's stations: empty importance-3 rung, and metro lines with no metro
stations (R75, R70) — this is #68 again, for the country #68's own note said it would
generalize to
#82 roads.surface is manufactured where the source is silent, in three countries
(R66) — the generalization of #6
#83 Cover vocabulary runs 13 to 32 classes across countries; two have no wetland at
all (R22, R44)
#84 Terrain, buildings and airports exist for Iceland alone (R13)
#85 Poland's two absent layers were ruled out against the fetched class list, not
BDOT10k's catalogue (R6) — the same shape as the Warsaw metro finding in #64
#86 Finland's railway lines carry no name at all (R93)

Four findings already had issues and were not re-filed: #12 (orphaned tables), #14 (Sweden's
missing wetland), #21 (water names), #45 (country borders).

They are filed unassigned. Assign them to art-bot to put them in the night-shift queue.

Documentation moved, not duplicated

#77 asked for general material to be moved out of the country docs and configs. Two
different treatments, for two different reasons:

docs/country-*.md — where a passage stated both the general rule and that country's
instance of it, the generalizing sentence is replaced by a citation and the
country-specific fact, number and column name stay. Each doc gains a header line pointing
at the new document.
conf/*.yaml — annotated, not edited. AGENTS.md makes the configs the review
surface for per-layer reasoning, so a reviewer reading a query should not have to leave the
file to learn why a threshold is what it is. The generic comments gain a one-line rule
citation and keep their text.

docs/generalization.md, docs/schema.md, docs/style.md and docs/architecture.md were
mined for requirements but not edited. They document mechanism, which is correctly scoped
where it is; the new document states what you must achieve and links to them for how.

Verification

Everything in the appendix is measured against the live database on main, not inferred:
per-country row counts for all 11 shared layers across every zoom, the eight empty
partitions in the whole database, attribute distributions per country for every enum column,
name IS NULL shares per layer, and html/style.json decoded for its source-layer and
zoom-range map. The style invariants asserted in R110 and R29 were re-checked against the
files (hsl(205, 55%, 74%) appears exactly 4 times; the only minz: in the configs is the
comment banning it).

No pipeline code changed and no import was run, so there is nothing to re-import to review
this.

Closes #77. ## What this is `docs/country-requirements.md` — 140 numbered requirements (`R1`…`R140`) describing what a country in this map has to look like, with a check for each one, and an appendix recording where the four current countries stood when it was written. The document is built from three sources, in the order #77 asked for them: 1. **How we do things today** — the layer inventory, the shared contracts, the cascade, the style invariants. 2. **Every issue, open and closed** — all 49 read, with the transferable rule extracted from each. Bug reports filed against one country turned out to generalize far more often than not; #64, #71, #29, #41 and #46 each yielded several requirements on their own. 3. **The country docs and the per-country configs** — passages that read as one country's reasoning but state a project-wide rule. `MUST` is a conformance requirement; `SHOULD` is a default a measurement may override, with the measurement going in the country doc. Numbers are stable identifiers, not a reading order, so a requirement added later never renumbers an existing one. ## The stronger requirement #77 asked for #77 said the capital should be the last name standing when every other name has generalized away, and the top five names should be the five largest cities. That became **R85**, and it is the requirement that did the most work: three of the four countries fail it. | country | z5 place labels | capital's rank | |---|---|---| | Iceland | `Ísland` | Reykjavík: not in the top 6, absent at z7 | | Poland | Białystok, Gdańsk, Katowice, Kielce | Warszawa: 15 | | Finland | FORSSA, HANKO, HEINOLA, HELSINKI | Helsinki: 4 | | Sweden | Stockholm, Göteborg, Västerås, Uppsala, Linköping, Malmö | Stockholm: 1 | Iceland's is the sharp one. Its five highest-ranked places are `Ísland` (the country), `Kolbeinsey` (an uninhabited skerry), `Sundhnúkur` (a crater row), `1000 manna hellir` (a cave) and `ABC Garðurinn`. `conf/ismap.yaml`'s `places` reads the whole `ornefni_punktar` toponym register and grades it by `örnefnaflokkurkenni`, which is a *category* code — land, sea, water, ice — not a size signal: 44,530 names at importance 1, two at 2, one at 3. With nothing to break ties the ranking falls straight to alphabetical. The reason nobody saw it: Iceland is still served the legacy `settlement_points` layer through the `is` tile source, and `html/style.json` draws both it and `places` from z4. The real town names come from the legacy layer, which masks the broken one — and means every Icelandic settlement is currently labelled twice. ## Issues filed Nine, #78–#86, one per non-conformance that did not already have an issue. Each cites the requirement numbers it violates and carries the query that found it. - **#78** Iceland's `places` ranks the toponym register, not settlements — and `settlement_points` double-labels the map (R85, R86, R91) - **#79** Poland's and Finland's place-name ladders go alphabetical at the top (R85, R87) - **#80** Finland's place register ships its top tier in capitals, and duplicates it cased (R94, R90) - **#81** Finland's stations: empty importance-3 rung, and metro lines with no metro stations (R75, R70) — this is #68 again, for the country #68's own note said it would generalize to - **#82** `roads.surface` is manufactured where the source is silent, in three countries (R66) — the generalization of #6 - **#83** Cover vocabulary runs 13 to 32 classes across countries; two have no wetland at all (R22, R44) - **#84** Terrain, buildings and airports exist for Iceland alone (R13) - **#85** Poland's two absent layers were ruled out against the fetched class list, not BDOT10k's catalogue (R6) — the same shape as the Warsaw metro finding in #64 - **#86** Finland's railway lines carry no name at all (R93) Four findings already had issues and were not re-filed: #12 (orphaned tables), #14 (Sweden's missing wetland), #21 (water names), #45 (country borders). They are filed unassigned. Assign them to `art-bot` to put them in the night-shift queue. ## Documentation moved, not duplicated #77 asked for general material to be moved out of the country docs and configs. Two different treatments, for two different reasons: - **`docs/country-*.md`** — where a passage stated both the general rule and that country's instance of it, the generalizing sentence is replaced by a citation and the country-specific fact, number and column name stay. Each doc gains a header line pointing at the new document. - **`conf/*.yaml`** — annotated, not edited. `AGENTS.md` makes the configs the review surface for per-layer reasoning, so a reviewer reading a query should not have to leave the file to learn why a threshold is what it is. The generic comments gain a one-line rule citation and keep their text. `docs/generalization.md`, `docs/schema.md`, `docs/style.md` and `docs/architecture.md` were mined for requirements but not edited. They document *mechanism*, which is correctly scoped where it is; the new document states what you must achieve and links to them for how. ## Verification Everything in the appendix is measured against the live database on `main`, not inferred: per-country row counts for all 11 shared layers across every zoom, the eight empty partitions in the whole database, attribute distributions per country for every enum column, `name IS NULL` shares per layer, and `html/style.json` decoded for its source-layer and zoom-range map. The style invariants asserted in R110 and R29 were re-checked against the files (`hsl(205, 55%, 74%)` appears exactly 4 times; the only `minz:` in the configs is the comment banning it). No pipeline code changed and no import was run, so there is nothing to re-import to review this.

art-bot added 1 commit

2026-08-09 10:40:32 +00:00

#77 : write down what a country has to look like, and audit the four we have 233b28cf2f

The four countries were built in order and each taught something the earlier
ones had already got wrong. Those lessons were spread across 49 issues, four
country docs and five configs, which meant the fifth country would have had to
rediscover them. docs/country-requirements.md collects them as 140 numbered
requirements with a check for each.

Built from three passes: how we do things today; every issue open and closed,
with the transferable rule extracted from each; and the passages in the country
docs and configs that read as one country's reasoning but state a project-wide
rule. #64, #71, #29, #41 and #46 each yielded several requirements on their own.

The requirement #77 asked for is R85 — the capital must be the last name
standing, and the top five must be the five largest cities. Three of the four
countries fail it. Iceland fails it hardest: its five highest-ranked places are
the country itself, an uninhabited skerry, a crater row, a cave, and a garden.
`places` reads the whole ornefni_punktar register and grades it by
örnefnaflokkurkenni, which is a category code, not a size signal — 44 530 names
at importance 1, so the ranking falls straight to alphabetical. Reykjavík is
absent at z7. It looks fine on screen only because the legacy settlement_points
layer still draws the real town names on top of the broken ones.

Nine issues filed, #78–#86, one per non-conformance without an existing issue.
#12, #14, #21 and #45 already covered four more.

The country docs keep their country-specific facts and cite the rule they are
an instance of; the generalizing sentences are gone. The configs are annotated
rather than edited — AGENTS.md makes them the review surface for per-layer
reasoning, so a reviewer reading a query should not have to leave the file.
generalization.md, schema.md, style.md and architecture.md were mined but not
touched: they document mechanism, which is correctly scoped where it is.

The appendix is measured against the live database, not inferred — per-country
row counts for all 11 shared layers at every zoom, the eight empty partitions in
the whole database, attribute distributions per country for every enum column,
and style.json decoded for its source-layer and zoom-range map.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>