jobtrackingapp/docs/global-jobs/00/GEOGRAPHY_DECISIONS.md

# Geography decisions — proposed, exact GJ-02 semantics

28 October 2026. The [GJ-02 prompt](../../planning/global-jobs-prompts/03_GJ_02_GEOGRAPHY.md) is authoritative. No geography ingestion, geometry validation or distance test was run in GJ-00.

## Source and identity decisions

| Country | Authoritative candidates / observed facts | Licence/version and unresolved qualification |
|---|---|---|
| NO | SSB county/municipality classifications; Kartverket administrative geometry and SSR official place names. Vestfold `39`, Tønsberg municipality `3905`, Sandefjord `3907`; Vestland `46`, Bergen `4601`; Oslo county `03`, municipality `0301`. | Pin SSB 2026 IDs/validity plus exact Kartverket download/API metadata and geometry edition/hash in GJ02-A. Kartverket free products are CC BY 4.0, credit © Kartverket and link. Verify SSB export licence separately. SSR point/name is not a settlement polygon. |
| SE | SCB län/kommun plus statistical tätort/locality. Stockholm municipality `0180` must remain distinct from Stockholm settlement; settlement boundaries may cross municipality boundaries. | SCB publishes CC0 simplified county/municipality boundaries but explicitly says they are unsuitable for analysis. Choose qualified Lantmäteriet administrative geometry for exact spatial work or disclose lower precision. Pin exact current SCB locality edition at GJ02-A (2023 listed on inspected download page); verify metadata, not “latest” URL. |
| GB | ONS/GSS administrative IDs, lookup relations and settlement geography; country-specific settlement sources for Scotland/NI need qualification. Warwickshire `E10000031` contains Warwick district `E07000222`; district contains both Warwick and Royal Leamington Spa parishes. Neither district nor a combined built-up area is Warwick town alone. | ONS OGL v3 + product-specific OS/other attribution; Northern Ireland postcode data needs a separate commercial licence. Pin individual product epoch/hash. Exact Warwick/Leamington settlement IDs/geometries and Scottish/NI settlement metadata remain GJ02-A blockers to precision claims. No made-up town IDs. |

Official sources accessed 2026-10-28: [SSB county 2026](https://dataportal.ssb.no/classifications/104/versions/3315/correspondences/2808), [SSB municipalities](https://dataportal.ssb.no/classifications/131/correspondences/1358), [Kartverket services](https://www.kartverket.no/en/api-and-data/eiendomsdata/apent-tilgjengelige-data-og-tjenester), [Kartverket terms](https://www.kartverket.no/api-og-data/vilkar-for-bruk), [SSR guide](https://kartverket.no/en/api-and-data/stedsnavndata/brukarrettleiing-stadnamn-api), [SCB boundaries](https://www.scb.se/hitta-statistik/regional-statistik-och-kartor/regionala-indelningar/digitala-granser/), [SCB localities](https://www.scb.se/vara-tjanster/oppna-data/oppna-geodata/statistiska-tatorter/), [Warwickshire](https://www.ons.gov.uk/explore-local-statistics/areas/E10000031-warwickshire), [Warwick district/parishes](https://www.ons.gov.uk/explore-local-statistics/areas/E07000222-warwick), [ONS licences](https://www.ons.gov.uk/methodology/geography/licences/).

## Canonical contract

`LocationNode` has stable internal ID, source namespace/code/type/country, edition, validity, original/localized names and aliases, optional geometry/representative point with CRS/precision/provenance, and deprecation/replacement links. External code identity is versioned; no code is assumed eternal or globally unique. Preserve original provider location and confidence (`exact`, `area-only`, `approximate`, `unresolved`). Postal areas are not administrative ancestry.

Use typed relationship edges (`administrative-parent`, `settlement-intersects`, `alias-of`) rather than one false universal tree. Country → county/län → municipality/district → town is a **navigation projection** where valid; unitary authorities skip absent levels. Settlement overlaps remain many-to-many. Oslo has distinct county/municipality type identities linked to the same administrative footprint; selecting one should not duplicate results. Tønsberg municipality and settlement likewise remain distinct. Stockholm settlement does not become wholly contained in Stockholm municipality by UI nesting.

`LocationScope` serializes branch root + explicit refinements + mode (`whole`/`specific`) + optional radius origins, schema version and taxonomy edition. Store scopes, not thousands of child checkboxes. Browser tree expansion is lazy/paginated and independent of selection; collapsed branches retain filters. Unknown/stale IDs cause visible review, never silently broaden to a parent. Dataset upgrades retain old IDs and versioned crosswalks; ambiguous replacements require confirmation.

## Exact interaction/query contract

For a selected branch b: effective(b) = union of its explicit deepest refinements when any exist; otherwise whole selected root. Recurse the same rule for nested refinements. Combine independent branches as OR; combine location with occupation/language/other dimensions as AND. Explicit selections on one ancestry path refine that path, never add the broad parent back into the OR union. A separately selected whole-country branch must visibly explain that it subsumes narrower branches.

| Action / state | Effective query | Visible state |
|---|---|---|
| Select Warwickshire | Whole county | County selected, children unchecked |
| Expand only | Still whole county | Expansion changes no filters |
| Select Warwick under selected Warwickshire | Warwick **town only** | County retained as scope being refined; `Warwick only` summary |
| Add Royal Leamington Spa | Warwick town OR Royal Leamington Spa town | Both refinements; no other county areas |
| Remove Warwick | Royal Leamington Spa only | Summary updates |
| Remove last town, keep county | Whole Warwickshire | Whole area state restored |
| Add Bergen branch | Previous effective GB scope OR chosen Bergen scope | Country branches both visible |
| Deselect county | Remove that branch and its descendants | Announce removal; no hidden child filters |
| Collapse / reopen / save / reload | Same scopes | Checked scope/refinement distinction preserved |

Use a scope checkbox plus separate Whole area/Specific places controls and effective summary. Do not expose a checked parent as the conventional “all descendants selected” or mixed-state checkbox. A direct town selection through lookup includes ancestry for navigation; deselecting that selected ancestor clears the associated branch visibly. Do not auto-check children when selecting a parent.

Provider query compiler emits supported area IDs and a local exact filter over permitted data. Provider codes need versioned canonical mapping; ambiguous text alone remains unresolved. A county-only posting cannot pass a strict Warwick-town filter. Approximate/unresolved results may appear only in an explicitly labelled optional broad-results section, excluded from exact counts/alerts. No `Contains("Warwick")` geography. Live-query result-window limits prevent exhaustive local filtering claims.

## Optional radius and remote rules

Radius is off by default. Choose town origin(s) explicitly with known point provenance; examples 10/25/50 km. Radius replaces the town polygon test for that origin, so nearby places outside the parent boundary may be included; keep the selected **country** constraint and disclose “within X km of town”, not “town only”. Multiple origins OR together; whole-area branches still OR with radius branches. Different dimensions still AND. Do not apply a county centroid as if it were a town or job coordinate.

Compute geodesic distance on WGS84 coordinates, inclusive boundary with documented numerical tolerance and fixture points just inside/outside. Missing/area-centroid-only job coordinates fail strict radius membership and remain visibly unknown. No driving-time claim; actual commute time requires a separately licensed routing provider, deferred.

Remote filter is explicit: on-site/hybrid use workplace scope/radius; fully remote matches selected work-country eligibility where declared, with geographic/radius exception visibly labelled and opt-in; region-limited remote still requires that declared region. Unknown eligibility does not mean worldwide. Work location constraints cannot be bypassed by a remote tag.

## GJ02 acceptance obligations

Freeze real licensed IDs/geometries for Warwickshire/Warwick/Leamington, Vestfold/Tønsberg/Sandefjord, Vestland/Bergen, Oslo dual identity and Stockholm län/municipality/settlement. Test all transitions above, nested/sibling branches, cross-country OR, unitary/overlapping geography, stale IDs, missing coordinates, radius bounds, provider code mismatch and persistence roundtrips. Measure index/query plan, lazy lookup and accessible mobile/keyboard behavior; never render 1,000 child checkboxes. Until exact settlement data is qualified, town-precision implementation remains blocked rather than using district substitutes.