Address-coverage "fog of war" overlay

Audience

🧪 Operator / agent runbook. Everything you need to rebuild, republish, extend, or debug the demo map's coveragecoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present. overlay with zero prior context. Shipped via PR #737 (merged to main).

What it is

A demo-map overlay that answers "where do we need data" at a glance — covered → clear (basemap shows through), uncovered → gray fog. Two layerslayerOne transformer block — attention plus a feed-forward network, with normalization and residual connections — applied to every position. Stacking layers lets the model build up richer representations; Mailwoman's encoder has 6. in one tileset:

1. US rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few metres — the highest tier of the geocode cascade. Sourced from address-point and situs data. fine map — shades each US area by address-point density (streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels./block detail). The original overlay; reveals the "looks covered until you zoom in, then the gaps go gray" holes.
2. Global "work to do" holes (fog = salience·(1 − coverage)) — populated places worldwide that we can't geocode yet show as gray-fog holes, weighted by importance (big uncovered cities are darkest). PostcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one./rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few metres — the highest tier of the geocode cascade. Sourced from address-point and situs data. coveragecoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present. clears the hole, so the holes land where civilization exists but our data doesn't — Africa, the Middle East, C/S Asia, South America, and gaps like UK/Ireland (Royal Mail isn't in open GeoNamesGeoNamesA free global gazetteer combining administrative, postal, and POI data across 200+ countries. Supplements Who's On First for postcode centroids and places where WOF has gaps.).

• Live: https://tiles.sister.software/coverage-v5.json (XYZ vector tiles via the tile worker).
• In the demo: the LayerslayerOne transformer block — attention plus a feed-forward network, with normalization and residual connections — applied to every position. Stacking layers lets the model build up richer representations; Mailwoman's encoder has 6. panel (top-right) has two default-off toggle groups — CoveragecoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present. · optimistic fog and CoveragecoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present. · honest fog. The user picks one.
• CoveragecoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present. today: US rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few metres — the highest tier of the geocode cascade. Sourced from address-point and situs data. = 48 statesregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. + DC + VI (Overture) + HI (OpenAddressesOpenAddresses (OA). A global open aggregation of address points collected from many official sources. A primary source of component-supervised training data outside proprietary registries.) + NH (streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.-level), AK excluded (antimeridian). Global postcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one. coveragecoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present. = GeoNamesGeoNamesA free global gazetteer combining administrative, postal, and POI data across 200+ countries. Supplements Who's On First for postcode centroids and places where WOF has gaps. allCountries postal (121 countries) clearing the holes; civilization backdrop = WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. settlement places weighted by place_importance.

Architecture (read this before touching anything)

It is an H3H3Uber's hexagonal hierarchical geospatial indexing system. Mailwoman uses H3 cells at resolution 9 (~0.03 km²) for geo-first blocking in the matcher and for stable address primary keys in @mailwoman/address-id. hexbin tileset. Each cell carries two baked fog values in [0,1] (0 = covered/clear, 1 = empty/gray):

• fog — honest: fine cells use point density; coarse cells use the mean child coveragecoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present. fraction.
• fog_opt — optimistic: fog ** gamma (γ>1) lifts partial coveragecoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present. toward clear, so a regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. "looks covered" zoomed out and the gaps surface on zoom-in.

The demo's two fill layerslayerOne transformer block — attention plus a feed-forward network, with normalization and residual connections — applied to every position. Stacking layers lets the model build up richer representations; Mailwoman's encoder has 6. (coverage-opt-fog, coverage-honest-fog) just point fill-opacity at one prop or the other — no rebake needed to switch readings. Each H3H3Uber's hexagonal hierarchical geospatial indexing system. Mailwoman uses H3 cells at resolution 9 (~0.03 km²) for geo-first blocking in the matcher and for stable address primary keys in @mailwoman/address-id. resolution is baked in its own non-overlapping zoom band; the finest is baked at a single tile-max zoom and MapLibre overzooms above it (hexes are identical geometry at every zoom).

Serving is XYZ via the tile worker — NOT client-side PMTiles. The .pmtiles archive lives at nexus-assets/tiles/coverage-v5.pmtiles and the tile-worker/ Cloudflare Worker serves it as tiles.sister.software/coverage-v5/{z}/{x}/{y}.mvt (exactly like basemap-v4). A previous iteration served the PMTiles directly through the pmtiles:// protocol — that was wrong and was removed (524f78a8). Don't bring it back.

The global holes layerlayerOne transformer block — attention plus a feed-forward network, with normalization and residual connections — applied to every position. Stacking layers lets the model build up richer representations; Mailwoman's encoder has 6. is decoupled from the US rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few metres — the highest tier of the geocode cascade. Sourced from address-point and situs data. pipelinestaged pipelineMailwoman's runtime architecture: a sequence of pure-function stages (normalize → query-shape → locale-gate → kind-classifier → phrase-grouper → classifier → decoder) connected by typed handoffs. Each stage is published as its own npm package. (its own DuckDB stagestageOne of the dataflow stages in the runtime pipeline (normalize, locale gate, kind classify, phrase group, token classify, sequence correct, reconcile, resolve). Distinct from tier (model vocabulary) and phase (plan milestone)., US-excluded) but rides the SAME coverage source-layerlayerOne transformer block — attention plus a feed-forward network, with normalization and residual connections — applied to every position. Stacking layers lets the model build up richer representations; Mailwoman's encoder has 6. + fog/fog_opt props, so the demo's two fill layerslayerOne transformer block — attention plus a feed-forward network, with normalization and residual connections — applied to every position. Stacking layers lets the model build up richer representations; Mailwoman's encoder has 6. render it with zero wiring changes. It emits res-domain hexes at [onset…max] + a res-4 low-zoom rollup; the US tierstierInternal versioning of which label classes the model emits. Tier 1 is the coarse components (country, region, locality, postcode); Tier 2 adds venue, street, house_number; Tier 3 (future) would add attention, po_box, and POI venue subtyping. Historically called 'Stage 1/2/3' before the runtime-pipeline naming made that ambiguous. are untouched.

Code map

File	Role
mailwoman/coverage-core.ts	The build pipelinestaged pipelineMailwoman's runtime architecture: a sequence of pure-function stages (normalize → query-shape → locale-gate → kind-classifier → phrase-grouper → classifier → decoder) connected by typed handoffs. Each stage is published as its own npm package. (React-free): DuckDB H3H3Uber's hexagonal hierarchical geospatial indexing system. Mailwoman uses H3 cells at resolution 9 (~0.03 km²) for geo-first blocking in the matcher and for stable address primary keys in @mailwoman/address-id. aggregation → NDJSON → tippecanoe → PMTiles. The fog modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.' lives here.
mailwoman/commands/coverage/build.tsx	mailwoman coverage build — thin Ink wrapper over coverage-core.
mailwoman/commands/tiles/publish.tsx	mailwoman tiles publish — rclone upload of a PMTiles to an R2 bucket (multipart).
cartographer/coverage/index.ts	CoverageTileSetID (= "coverage-v5"), the two fog fill layerslayerOne transformer block — attention plus a feed-forward network, with normalization and residual connections — applied to every position. Stacking layers lets the model build up richer representations; Mailwoman's encoder has 6., fog color/opacity, createCoverageSource.
scripts/build-importance.ts	Builds place_importance (Wikipedia importanceWikipedia importanceA place-notability score derived from the count and language spread of a place's Wikipedia articles, normalized to [0, 1]. A resolver ranking prior that helps pick the prominent same-named place. + population fallback) — the holes-layerlayerOne transformer block — attention plus a feed-forward network, with normalization and residual connections — applied to every position. Stacking layers lets the model build up richer representations; Mailwoman's encoder has 6. salience source.
docs/src/pages/demo/index.tsx	Demo wiring — registers the coveragecoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present. source + adds the default-off layerslayerOne transformer block — attention plus a feed-forward network, with normalization and residual connections — applied to every position. Stacking layers lets the model build up richer representations; Mailwoman's encoder has 6. on map load.
docs/src/components/LayerToggleControl/LayerToggleControl.tsx	The toggle-group patterns (coverage-opt, coverage-honest).
scripts/build-address-point-shard.ts	Per-stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. situssitusThe physical site address of a property, as opposed to the owner's mailing address. Parcel records often carry both; the divergence is a real-world data-quality challenge. shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. builder. --oa-csv mode reads OpenAddressesOpenAddresses (OA). A global open aggregation of address points collected from many official sources. A primary source of component-supervised training data outside proprietary registries. for statesregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. Overture omits (HI).

Source data (NOT in git): the per-stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. US rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few metres — the highest tier of the geocode cascade. Sourced from address-point and situs data. shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. $MAILWOMAN_DATA_ROOT/address-points/address-points-us-<st>.db (124.9M points) + …/interpolation/interpolation-us-<st>.db (TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data. segmentssegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context.); the global postcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one. signal …/geonames/allCountries-postal.txt (GeoNamesGeoNamesA free global gazetteer combining administrative, postal, and POI data across 200+ countries. Supplements Who's On First for postcode centroids and places where WOF has gaps. postal, 121 countries); and the civilization backdrop …/wof/admin-global-priority-importance.db (WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. spr + place_importance, built by scripts/build-importance.ts).

Runbook: rebuild + republish

0. Refresh the civilization backdrop (only when WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. or the importance data changes) — place_importance keys the holes layerlayerOne transformer block — attention plus a feed-forward network, with normalization and residual connections — applied to every position. Stacking layers lets the model build up richer representations; Mailwoman's encoder has 6.'s salience. Build it onto a COPY of the canonical WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. DB so the gazetteergazetteerA geographical index that maps place names and postcodes to real-world coordinates. Mailwoman uses a custom-built Who's On First (WOF) SQLite database as its gazetteer — the 'atlas' half of the grammar/atlas architecture. the resolverresolverThe component that converts parsed address components (locality, region, postcode) into coordinates by looking them up in the gazetteer. The resolver ranks candidates by name match, population, and proximity, and returns the best-matching place with its centroid or polygon. uses stays untouched:

cp $MAILWOMAN_DATA_ROOT/wof/admin-global-priority.db \
   $MAILWOMAN_DATA_ROOT/wof/admin-global-priority-importance.db
npx tsx scripts/build-importance.ts --db $MAILWOMAN_DATA_ROOT/wof/admin-global-priority-importance.db
# Downloads Nominatim's wikimedia-importance.csv.gz (needs a browser User-Agent — it 403s curl's default).

1. Build the tileset (maintainer-only — needs the local shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. + tippecanoe on PATH + the @duckdb/node-api dev dep):

mailwoman coverage build --states all --exclude-states AK \
  --out $MAILWOMAN_DATA_ROOT/coverage/coverage-global-v5.pmtiles
# ~10–15 min; archive ≈ 1 GiB. The global holes layer is on by default (--no-postcode to skip it).
# --keep-ndjson to re-tile without re-aggregating.

2. Publish to the tile-worker bucket (nexus-assets):

set -a; . ./.env; set +a
# nexus-assets is written by the *_PUBLIC_* R2 keys (see gotcha below):
RCLONE_S3_ACCESS_KEY_ID="$RCLONE_S3_PUBLIC_ACCESS_KEY_ID" \
RCLONE_S3_SECRET_ACCESS_KEY="$RCLONE_S3_PUBLIC_SECRET_ACCESS_KEY" \
RCLONE_S3_ENDPOINT="$RCLONE_S3_PUBLIC_ENDPOINT" \
RCLONE_S3_PROVIDER=Cloudflare RCLONE_S3_REGION=auto \
mailwoman tiles publish --file $MAILWOMAN_DATA_ROOT/coverage/coverage-global-v5.pmtiles --tileset coverage-v5

3. Verify: curl -s -o /dev/null -w '%{http_code}' https://tiles.sister.software/coverage-v5.json → 200.

Re-versioning: the object is at a versioned path (coverage-v5). To ship a fresh bake, bump CoverageTileSetID in cartographer/coverage/index.ts to coverage-v6, upload to tiles/coverage-v6.pmtiles, and the demo follows automatically. (Versioning avoids R2 cache-staleness; same pattern as basemap-v4.)

Credential + upload gotchas (this cost a whole session — read it)

• Which keys write nexus-assets: the RCLONE_S3_PUBLIC_* keys. The plain RCLONE_S3_* keys are scoped to mailwoman-assets and 403 on nexus-assets (read and write). CF_AUTH_TOKEN is the Cloudflare API tokentokenOne word or subword in the tokenized input. For the neural classifier, tokens come from SentencePiece (subword units); for the rule classifiers, tokens are whitespace- and punctuation-separated words. (wrangler).
• wrangler r2 object put hard-caps at 300 MiB — useless for these archives. rclone does multipart with no cap — that's why tiles publish uses rclone, not wrangler.
• nexus-public ≠ nexus-assets. nexus-public (public.sister.software/mailwoman/, the scripts/publish-demo-assets-to-r2.py target) hosts the demo's modelneural classifierThe machine learning model at the core of Mailwoman's parser — a transformer encoder (~30M parameters) trained from scratch to do BIO token classification over addresses. It learns the 'grammar' of address formats; the gazetteer supplies the 'atlas.'/DBs/shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row.. The tile worker reads nexus-assets. Don't put tiles in nexus-public.

Data state + the HI/NH situation

StateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. group	Source	Notes
48 statesregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. + DC + VI	Overture addresses 2026-05-20.0	build-address-point-shard.ts (default).
HI	OpenAddressesOpenAddresses (OA). A global open aggregation of address points collected from many official sources. A primary source of component-supervised training data outside proprietary registries.	Overture omits Hawaii entirely (verified at the S3 source — 0 rows in both releases). Built via build-address-point-shard.ts --oa-csv <4 county CSVs> → 348K rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few metres — the highest tier of the geocode cascade. Sourced from address-point and situs data. points.
NH	TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data. interpolationinterpolationA geocoding technique that estimates a coordinate along a street segment based on the house number range. Used as the middle tier of Mailwoman's geocode cascade when exact address-point data is unavailable. only	No rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few metres — the highest tier of the geocode cascade. Sourced from address-point and situs data. source exists — OA's only NH run is coordinate-only (0 usable of 610K), Overture absent. NH renders streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.-level (visibly a less-covered regionregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. — honest). Real NH rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few metres — the highest tier of the geocode cascade. Sourced from address-point and situs data. points = NH GRANIT (not yet done).
AK	excluded	Antimeridian: h3_cell_to_boundary_wkt emits unwrapped lon for Aleutian cells. Needs antimeridian splitting before inclusion.

To add an Overture-gap stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. from OpenAddressesOpenAddresses (OA). A global open aggregation of address points collected from many official sources. A primary source of component-supervised training data outside proprietary registries.: download the OA conformed CSV(s) from results.openaddresses.io/latest/run/us/<st>/<source>.zip, then build-address-point-shard.ts --state <ST> --oa-csv <csv1>,<csv2>,…. The shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. is picked up automatically on the next coverage build.

Tuning knobs (coverage build)

Flag	Default	Effect
--fine-res	9 (≈174 m, streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels./block)	Finest grid. Dominates size. res-8 ≈ 460 m, res-7 ≈ 1.2 km.
--domain-res	6 (≈3.2 km)	Fog-halo extent around coveragecoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present.. Tighter (7, 8) → smaller but hugs coveragecoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present..
--saturation / --sat-seg	25 / 8	Point / segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context. count at which a cell fully clears.
--interp-weight	0.4	WeightparameterA single learned number inside a model — one weight or bias. Mailwoman's encoder has roughly 30 million of them; training is the search for good values. of the TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data. streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. signal vs address pointssitus dataA dataset of exact address-point coordinates (rooftop-level). Mailwoman's geocoder uses a national situs layer (124.9M US points built from state address-point sources) as the highest-precision tier of the geocode cascade. (< 1, so streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.-only never fully clears).
--optimistic-gamma	2.0	The fog_opt = fog ** gamma exponent.
--max-zoom	12	Highest baked zoom; overzoom above.

Global holes layerlayerOne transformer block — attention plus a feed-forward network, with normalization and residual connections — applied to every position. Stacking layers lets the model build up richer representations; Mailwoman's encoder has 6. (fog = salience·(1 − coverage), res-domain hexes, US-excluded):

Flag	Default	Effect
--no-postcode	(on)	Disable the global holes layerlayerOne transformer block — attention plus a feed-forward network, with normalization and residual connections — applied to every position. Stacking layers lets the model build up richer representations; Mailwoman's encoder has 6. entirely — US rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few metres — the highest tier of the geocode cascade. Sourced from address-point and situs data. fine map only.
--geonames-postal	…/geonames/allCountries-postal.txt	The postcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one. COVERAGEcoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present. signal — a postcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one. present in a domain cell clears its hole.
--wof-db	…/wof/admin-global-priority-importance.db	The civilization backdrop — spr + place_importance (settlement salience).
--postcode-ceiling	0.85	How much a postcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one. cell clears the hole (≤ 1; rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few metres — the highest tier of the geocode cascade. Sourced from address-point and situs data. is the full 1).
--salience-floor	0.15	Min place importance to flag as a hole — the noise floor (raise to keep only the notable holes).
--postcode-exclude	US	Countries the holes layerlayerOne transformer block — attention plus a feed-forward network, with normalization and residual connections — applied to every position. Stacking layers lets the model build up richer representations; Mailwoman's encoder has 6. skips (handled by the rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few metres — the highest tier of the geocode cascade. Sourced from address-point and situs data. fine map).

The salience is sqrt(importance) — lifts modest uncovered towns to a visible gray while keeping big cities darkest. Holes below 0.05 residual fog (covered or trivial) are dropped, so the layerlayerOne transformer block — attention plus a feed-forward network, with normalization and residual connections — applied to every position. Stacking layers lets the model build up richer representations; Mailwoman's encoder has 6. is just the holes (~290 K res-6 cells); covered + empty stay clear.

National size by --fine-res (res-9 d6 measured): res-9 ≈ 848 MiB, res-8 ≈ 364 MiB, res-7 ≈ 55 MiB. Only res-7 fits wrangler's 300 MiB cap — irrelevant now that rclone-multipart works, so we ship the full res-9.

Gotchas (learned the hard way)

• DuckDB multi-ATTACH mis-binds. ATTACHing N sqlite DBs and UNION ALL-ing structurally-identical aggregating subqueries (h3_latlng_to_cell(…) … GROUP BY 1 per arm) silently binds every arm to the first attached DB (a 49-stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. build reported 3× CA's points in CA's cells). Fix: UNION ALL the raw columns, aggregate once in the outer query. (Already done in coverage-core.ts — don't undo it.)
• .gitignore bare coverage rule (the vitest report dir) matches any dir named coverage at any depth — it was silently swallowing mailwoman/commands/coverage/ and cartographer/coverage/. Scoped !-negations are in .gitignore; keep them or the command + module vanish from git/npm-publish.
• Don't serve PMTiles client-side. XYZ via the tile worker only.
• The holes layerlayerOne transformer block — attention plus a feed-forward network, with normalization and residual connections — applied to every position. Stacking layers lets the model build up richer representations; Mailwoman's encoder has 6. is res-domain-coarse on purpose. PostcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one./importance is area-scale; it does NOT subdivide to res-9 (that would multiply the archive ~343×). EU/global reads at ~3.2 km granularity, overzoomed above z12 — accurate, since a postcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one. IS coarse. Don't "finish" it to streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. level.

Follow-ups / open work

1. Close real holes with rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few metres — the highest tier of the geocode cascade. Sourced from address-point and situs data./postcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one. data. The map now NAMES the gaps — biggest wins: UK/Ireland (Royal Mail isn't in open GeoNamesGeoNamesA free global gazetteer combining administrative, postal, and POI data across 200+ countries. Supplements Who's On First for postcode centroids and places where WOF has gaps.; needs Code-Point Open or OA), and the Overture-EU address parquetsParquetThe open columnar file format the corpus is written and streamed in. The training pipeline reads shards row-by-row from Parquet. already on disk (…/overture/<rel>/addresses-<cc>.parquet) → real EU rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few metres — the highest tier of the geocode cascade. Sourced from address-point and situs data. shardsshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. (would upgrade EU from postcodepostcodeThe country-specific postal code (US ZIP, French code postal, etc.). Mailwoman handles postcode parsing entirely by rule classifier — a regex problem, not an ML one.-coarse to streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.-level + clear more holes).
2. NH rooftoprooftopGeocoding precision at the building or parcel level — coordinates within a few metres — the highest tier of the geocode cascade. Sourced from address-point and situs data. points via NH GRANIT — NH is streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.-level only today.
3. AK — the antimeridian guard now DROPS wrapped hexes (so AK partial-renders if its shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. is included); a proper fix splits the boundary at ±180 in coverage-core.ts instead of dropping.
4. Importance refresh cadence — place_importance is built onto a WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations.-DB copy; re-run build-importance when WOFWOF (Who's On First). An open-source gazetteer of places maintained by Mapzen/whosonfirst. Mailwoman builds a custom SQLite database from WOF GeoJSON repos, extended with postcode data, importance scores, and coincident-role relations. or the Nominatim importance dump refreshes, then re-bake.
5. Browser perf — the ~1 GiB / 59M-featurefeatureAn input signal a model conditions on. Beyond the raw tokens, Mailwoman feeds soft features — gazetteer-membership channels and the postcode anchor — that inform predictions without overriding them. archive serves per-tile (fine in practice), but worth watching dense-metro z12 tile sizes if it feels slow.

See also

• Data, locales, and coverage — the coveragecoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present.-claims concept page this overlay makes visible on the demo map