Skip to main content

House-number interpolation — design (#483, slice 1)

First slice of the 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. tiertierInternal 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. scoped in 2026-06-11-geocoder-table-stakes-scoping.md: "123 Main St" where no address point exists → estimate the coordinate between known ranges along the streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context.. This document covers the pilot — a Vermont-scoped TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data. EDGES segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context. table, a standalone 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. module in resolver-wof-sqlite, and the honest evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. that grades it against real 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..

Where it sits in the resolution ladder​

exact address point  (#476, AddressPointSqliteLookup — situs coordinate, tier "address_point")
        ↓ miss
interpolation        (#483, StreetInterpolator — THIS DOC, tier "interpolated")
        ↓ miss
admin centroid       (locality/region/country — the existing WOF resolver answer)

The interpolator only ever answers when the exact-point tiertierInternal 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. missed, and its answer is always flagged: interpolated: true plus an uncertaintyM radius (half the matched segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context.'s length — the honest default from the #483 issue). Same honesty convention as reverse.ts's containment: "approximate" and the demo's approximate circles: data reality surfaced per result, never hidden.

Data: TIGER EDGES​

The same per-county shapefiles the real-intersectionintersectionAn address that names a location by two crossing streets ('5th & Main') rather than a number and street. Mailwoman tags the two streets as intersection_a and intersection_b — a negative-space format that starved the early model. evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. already reads (scripts/eval/build-intersection-real.ts, DuckDB spatial ST_Read, downloaded from www2.census.gov/geo/tiger/TIGER2023/EDGES/tl_2023_<countyfips>_edges.zip into /tmp/tiger-edges/). Each road edge carries:

FieldMeaning
FULLNAMEStreetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. name as TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data. spells it (State Route 12, Main St)
LFROMADD/LTOADDHouse-number range on the LEFT side, walking from→to node
RFROMADD/RTOADDHouse-number range on the RIGHT side
ZIPL/ZIPRZIP code per side
MTFCCFeaturefeatureAn 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. class — S1… is a road
geomThe segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context. polyline (WGS84 lon/lat)

TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data. conventions that shape the schema:

  • Sides are independent. Left and right carry separate ranges and separate ZIPs (a streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. can be a ZIP boundary). We emit one ROW PER SIDE, not per edge.
  • Parity is per side, by convention but not by contract. Typically one side of a US streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. is odd and the other even, and TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data.'s from/to numbers usually agree on parity (Vermont: 137,248 of 137,256 sides). When from/to parity DISAGREES the side is recorded parity = "mixed" and matches either parity. Per-side fidelity is an open question below — we measure it, we don't assume it.
  • Ranges may descend. from > to means house numbershouse numberThe numeric or alphanumeric identifier of a building on a street. Mailwoman's house_number component; its position relative to the street name flips between locales. decrease walking from-node → to-node. The row keeps the raw from/to (the 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. position needs the direction); the index columns store min/max for range matching.
  • Ranges are potential, not actual. TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data. ranges are theoretical capacity (100–198), not occupancy. Interpolating assumes uniform spacing across the range — the classic source of 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. error, which is exactly what the evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. measures.
  • Non-numeric house numbershouse numberThe numeric or alphanumeric identifier of a building on a street. Mailwoman's house_number component; its position relative to the street name flips between locales. exist (hyphenated Queens-style 12-34, alphanumeric suffixes). The pilot keeps numeric-only sides and counts what it skips.

Segment table schema​

One SQLite DB per stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality., built by scripts/build-interpolation-shard.ts (the build-address-point-shard.ts pattern: idempotent rebuild, provenance per row, THE shared streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. normalizer):

CREATE TABLE street_segment (
  street_norm  TEXT NOT NULL,   -- normalizeStreetForKey(FULLNAME) — the shared normalizer
  side         TEXT NOT NULL,   -- 'L' | 'R'
  from_hn      INTEGER NOT NULL,-- raw TIGER from (may exceed to_hn)
  to_hn        INTEGER NOT NULL,
  min_hn       INTEGER NOT NULL,-- min(from,to) — range-match column
  max_hn       INTEGER NOT NULL,
  parity       TEXT NOT NULL,   -- 'odd' | 'even' | 'mixed'
  postcode     TEXT,            -- ZIPL or ZIPR for this side
  county_fips  TEXT NOT NULL,   -- scope + provenance
  street_raw   TEXT NOT NULL,   -- FULLNAME as shipped
  geometry     TEXT NOT NULL,   -- JSON [[lon,lat],…] polyline, from-node first
  source       TEXT NOT NULL,   -- 'tiger:edges'
  release      TEXT NOT NULL    -- 'TIGER2023'
);
CREATE INDEX idx_seg_postcode ON street_segment (postcode, street_norm, min_hn);
CREATE INDEX idx_seg_street   ON street_segment (street_norm, min_hn);

Keying reuses resolver-wof-sqlite/street-normalize.ts — the SAME function the address-point shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. and lookup use (one normalizer, never two; the PLACETYPE_ORDER lesson) — plus canonicalizeRouteKey, a route-designatordesignatorThe closed-vocabulary leading word of a secondary-address phrase — 'Apt', 'Suite', 'Floor', 'PO Box', 'Level' — paired with an identifier to form a complete subpremise. fold applied by BOTH the builder and the lookup. Measured need: TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data. spells routes State Rte 100 / US Hwy 5 where E911E911 (Enhanced 911). County- and state-level emergency-dispatch address-point databases with full component breakdown. A lineage source for the situs and address-point layers used in geocoding./Overture say VT ROUTE 100 / US ROUTE 5 — the single largest streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.-name miss class in the VT evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. (+3.1pp 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. from the fold alone, no tail cost). The address-point tiertierInternal 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. does not apply the fold yet; adopting it there needs a #476 shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. rebuild (follow-up). Geometry is a plain JSON polyline: segmentssegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context. are short, the per-row cost is small at stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality. scale, and it keeps the reader dependency-free — revisit encoding only if a national build makes size hurt.

Scoping is 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.-first, like the address-point tiertierInternal 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.. TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data. edges carry no localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. name, so localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. scope can't be matched directly against this table — a known limitation of this slice (see open questions). Queries without 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. fall back to a statewide streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels.-name match, which is honest but ambiguous for common names ("Main Street" exists in many towns); the lookup ABSTAINS when the statewide candidates spanspanA contiguous range of characters or tokens in the input string, tagged with an address component type (street, locality, postcode, etc.). Parsed addresses are represented as collections of spans, possibly nested in a tree. multiple postcodespostcodeThe 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. with no way to pick.

Query algorithm (resolver-wof-sqlite/interpolation.ts)​

Given { street, number, postcode? }:

  1. NormalizenormalizeStage 1 of the runtime pipeline: deterministic input preprocessing (Unicode NFC, punctuation normalization, whitespace collapse). Returns a NormalizedInput with an offsetMap that maps normalized positions back to the raw input. streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. via normalizeStreetForKey; parseaddress parsingThe process of decomposing a free-text postal address string into structured components — house number, street name, locality, region, postcode, and country — so a geocoder can resolve them to coordinates. number as a non-negative integer (non-numeric → no answer, this tiertierInternal 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. doesn't guess).
  2. Candidate fetch — rows with street_norm equal and min_hn ≤ n ≤ max_hn, 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.-scoped when 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 given. A given ZIP that scopes to nothing is a MISS, not a statewide guess — the statewide retry was built and MEASURED (2026-06-11 VT evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error.): +2.3pp 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. but a poisoned tail (p99 1.0 → 20.8 km, max 204 km — a statewide-unique name can live in a far-away town), so it was reverted. Queries WITHOUT 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. match statewide and abstain unless every candidate agrees on a single ZIP.
  3. Parity match — prefer sides whose parity equals the number's parity, then mixed, then opposite-parity as a last resort (an opposite-parity hit is usually the right block, wrong side of the streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. — tens of meters, not kilometers; the result reports parityMatched: false so callers and the evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. can see it).
  4. Pick the tightest range (smallest max_hn − min_hn) among the preferred group — the most specific claim wins.
  5. Interpolate — t = (n − from_hn) / (to_hn − from_hn) (0.5 when the range is a single number), clamped to [0, 1], then walk the polyline by cumulative haversine arc length to the point at fraction t. Descending ranges need no special case: t is computed against the raw from/to, which already encodes direction.
  6. Answer — { lat, lon, interpolated: true, parityMatched, uncertaintyM, source, release } where uncertaintyM is half the segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context.'s polyline length in meters.

No side-of-streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. offset in this slice: TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data. centerline + half-segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context. uncertainty is the honest claim. Offsetting perpendicular by ~10 m to the matched side is a cheap follow-up once the evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. says the centerline is the dominant error term (it isn't — range uniformity is).

Resolver tier placement​

core/resolver/resolve.ts already runs the exact-point tiertierInternal 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. via opts.addressPoints (applyAddressPoint, stamping resolution_tier: "address_point"). The 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. tiertierInternal 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. slots in immediately after it as the fall-through: same (street, number, postcode, locality) extraction, consulted ONLY when the exact tiertierInternal 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. missed, stamping resolution_tier: "interpolated" + the uncertainty metadata.

This slice ships the module standalone and does NOT wire core. The wiring needs a second ResolveOpts member (or a widening of addressPoints into an ordered tiertierInternal 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. list) and that interface decision deserves its own review — noted as a follow-up on #483 rather than smuggled into the pilot. The module's find() signature is deliberately identical in shape to AddressPointLookup.find() so the wiring is mechanical when it lands.

Eval — honest-eval pattern at street grain​

scripts/eval/interpolation-eval.ts, self-reporting. The gold is the #476 address-point shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. (address-points-us-vt.db, Overture 2026-05-20.0 — NADNAD (National Address Database). A US Department of Transportation dataset of structured address points, added to the training corpus as a major source of real US addresses./E911E911 (Enhanced 911). County- and state-level emergency-dispatch address-point databases with full component breakdown. A lineage source for the situs and address-point layers used in geocoding.-lineage 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. points): an independent source from TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data., so grading against it is non-circular. For a deterministic held-out sample of Vermont points:

  • query (street_raw, number, postcode) through the interpolator,
  • 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 that found a segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context. at all,
  • coord error — haversine meters vs the true point, reported p50/p90 (plus the parity-matched/fallback split),
  • graded against the #483 pre-registered gate: p50 ≤ 50 m, p90 ≤ 150 m on the VT holdout before any rollout.

These are points the exact tiertierInternal 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. would mostly HIT — the evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. uses them precisely because truth is known. The production value is the complement (numbers with no point), where truth is unknowable; measuring on known points is the only honest proxy.

Pilot results (2026-06-11, VT, 5000-key sample, seed 42)​

  • 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. 82.0% (4100/5000 found a segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context.). Miss composition: 469 name-absent in TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data. (private roads, new subdivisions, E911E911 (Enhanced 911). County- and state-level emergency-dispatch address-point databases with full component breakdown. A lineage source for the situs and address-point layers used in geocoding.-only names like CHARBO UNKNOWN 6), 232 range-gaps within the right ZIP+name, 166 ZIP-mismatches (name+range exists in a neighbouring ZIP — the class the rejected statewide retry would have answered, badly), 33 range-gaps statewide.
  • Coord error vs truth: p50 66 m, p90 249 m (p99 1.0 km; parity-matched n=3927 p50 65 m / fallback n=173 p50 116 m). Median claimed uncertainty (half segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context. length) 137 m — the p50 error sits inside the claimed radius.
  • Gate: MISS. The pre-registered #483 gate (p50 ≤ 50 m, p90 ≤ 150 m) is NOT met — stated plainly, not re-baselined. The shortfall tracks rural Vermont's long sparse segmentssegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context. (median claimed uncertainty 137 m: the geometry itself caps precisionprecisionOf the spans the model labeled as a given tag, the fraction it got right. High precision means few false positives. Paired with recall to compute F1.) and TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data.'s uniform-spacing assumption. Next levers, in measured-first order: re-run on a denser county (the gate may simply be a rural-geometry artifact — measure before building), segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context. subdivision at OA point anchors, ZIP+4 snapping (#525). No rollout until a gate pass or a STATED re-baseline with operator sign-off.

Density characterization (2026-06-12, resolution-ladder Phase 1 step 1)​

Same evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error., same gate, same seed-42 5000-key sampling, on a dense county: Cook County IL (FIPS 17031; TIGER2023 EDGES + a county-scoped #476 shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. — Overture carries no county field, so the point shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. is PIP-filtered against the TIGER2023 COUNTY polygon via the builder's new --county-fips flag; 1,460,216 points, 231 ZIPs).

countycoveragecoverageThe 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.p50p90gate (≤50 / ≤150)
Cook IL (dense)87.8%41 m79 mPASS
Vermont (rural, re-run)82.0%66 m249 mMISS (unchanged)

Cook's median claimed uncertainty (half segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context. length) is 80 m vs Vermont's 137 m — the segmentsegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context. geometry itself is the divide. Verdict: the VT gate miss is substantially a rural-geometry artifact, not a method error. TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data. uniform-spacing 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. clears the gate where segmentssegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context. are short; long sparse rural segmentssegmentA punctuation-bounded chunk of the normalized input — the comma-separated parts of 'Portland, OR' — used to give downstream stages structural context. cap precisionprecisionOf the spans the model labeled as a given tag, the fraction it got right. High precision means few false positives. Paired with recall to compute F1. below the gate. Per the resolution-ladder plan this keeps Method 2 (address-point 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.) as the corrective for the sparse stratum, and any county-stratified gate re-baseline remains an operator sign-off, not made here.

Method 2 — address-point interpolation (2026-06-12, resolution-ladder Phase 1 step 2)​

resolver-wof-sqlite/address-point-interpolation.ts (AddressPointInterpolator): bracket the query number with REAL neighbor points from the #476 shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. on the same route-folded streetstreetThe named linear feature along which house numbers are ordered. Decomposes into a name plus street affixes; one of the Tier 2 fine labels. key (street_key, a new shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. column — the fold adoption the pilot deferred), interpolate linearly in house-number space between the bracket's centroids; single-sided bracket = extrapolation along the two nearest same-side numbers, capped at one pair-spanspanA contiguous range of characters or tokens in the input string, tagged with an address component type (street, locality, postcode, etc.). Parsed addresses are represented as collections of spans, possibly nested in a tree. (t ≤ 2), with an explicitly larger uncertaintyM; no bracket = fall through to TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data. range 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.. Hits carry method: "address_point" | "tiger_range" + bracket: "both" | "single".

Non-circularity: the lookup excludes every row at the queried house numberhouse numberThe numeric or alphanumeric identifier of a building on a street. Mailwoman's house_number component; its position relative to the street name flips between locales. by construction — a held-out key is only ever interpolated from non-held-out neighbor numbers. (This is also production-faithful: an on-file number is the exact tiertierInternal 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.'s answer, never this tiertierInternal 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.'s.) The prior evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. had no shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row.-side holdout to lean on, so the guarantee lives in the lookup, not the sampler.

Same evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error. (--mode ladder), same gate, same seed-42 samples. Pre-registered question: does Method 2 clear the gate on its bracketed stratum?

stratumVT nVT p50/p90Cook nCook p50/p90
method 2 — bracketed (both-sided)420050 m / 182 m480742 m / 61 m
method 2 — single-sided extrapolation38274 m / 223 m12146 m / 102 m
tiger_range fallback30169 m / 237 m5447 m / 124 m
all hits (ladder)488353 m / 191 m498242 m / 62 m
tigerTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data.-alone, same sample (baseline)410066 m / 249 m438941 m / 79 m
  • 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.: VT 82.0% → 97.7%, Cook 87.8% → 99.6% — bracketing answers most of TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data.'s name-absent/range-gap miss classes because the neighbor points ARE the E911E911 (Enhanced 911). County- and state-level emergency-dispatch address-point databases with full component breakdown. A lineage source for the situs and address-point layers used in geocoding./Overture names.
  • Gate on the bracketed stratum: Cook PASS (42/61). VT MISS — p50 50.5 m (over by 0.5 m), p90 182 m. Stated plainly: Method 2 moved VT's bracketed p90 249 → 182 m and its p50 66 → 50.5 m, and that is still a miss. Not re-baselined.
  • The VT residual is wide-bracket concentrated, and the claimed uncertaintyM (half bracket spanspanA contiguous range of characters or tokens in the input string, tagged with an address component type (street, locality, postcode, etc.). Parsed addresses are represented as collections of spans, possibly nested in a tree.) predicts it: bracketed rows claiming ≤ 100 m (71.4% of the stratum) measure p50 42 m / p90 116 m — inside the gate — while the > 250 m claims (7.2%) measure p50 143 m / p90 917 m. The Phase 5 calibrated-confidence work is the principled home for acting on that (per-tiertierInternal 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. P(error < X) by claimed uncertainty), not a quiet stratum re-cut here.

Open questions​

  1. Workspace split. This slice implements inside resolver-wof-sqlite (the module is small, shares the normalizer + geo helpers, and ships nothing by default). The scoping note leaned toward a new @mailwoman/resolver-interpolation workspace — different data lifecycle (TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data. yearly vintages vs 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.), the slim/fat split the demo taught. Operator call before this grows beyond a pilot: stay (one fewer package, shared normalizer stays intra-package) vs split (independent versioning of the TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data. data contract). Nothing in this slice blocks either answer.
  2. Odd/even fidelity. Vermont measures 99.99% of address-carrying sides parity-consistent (8 mixed of 137,256), but a clean from/to pair doesn't prove the real houses obey it, and TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data. does not guarantee it nationally; the mixed bucket and the opposite-parity fallback are the pressure valves. The evalevalRunning the model against a held-out golden dataset and computing per-component F1, exact-match, calibration, and resolved-coordinate error.'s parity-split reporting is the instrument — if fallback hits dominate the error tail in a denser stateregionThe first-level administrative subdivision of a country — a US state, a French region, a province. The component between country and locality., revisit before national rollout.
  3. LocalitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. scope. TIGERTIGERThe US Census Topologically Integrated Geographic Encoding and Referencing database. Used as a corpus source for street-segment data. carries ZIPs, not localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. names. A localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy.-only query (no 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.) currently rides the statewide fallback + abstention. Joining ZIP → localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. via 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. shardshardA partial output file of the corpus build, written in Parquet format. The training pipeline streams shards row by row. (or place ancestry) would restore localitylocalityThe city / town / settlement component of an address: a populated place sitting between region and neighbourhood in the hierarchy. scoping — follow-up, not pilot.
  4. ZIP+4 snapping — deferred to #525 (needs the ZCTAZCTA (ZIP Code Tabulation Area). The US Census Bureau's polygon approximation of a ZIP code, generalized from census blocks rather than USPS delivery routes. Explicitly not USPS ground truth and often wrong in rural areas. work as a prior), per scoping.
  5. EU rollout — OSMOpenStreetMap (OSM). A community-curated global map database (ODbL-licensed) with addr:* tagged features and place hierarchies. A secondary corpus source and a source of street names. Karlsruhe-schema addr:interpolation ways, with the ODbL share-alike treatment documented in #26. Out of scope for the US pilot.