Rework LP-0018 region model, add adoption criteria, freeze region set.

Introduce a country/subregion region model with a non-overlap invariant
and Geofabrik-path keys, add parent/level to the registry schema, and
thread the model through success criteria, scope, and the appendix.

Add an Adoption section with independently verifiable coverage,
redundant mirroring, freshness, and sustained-activity criteria plus a
testnet-reset contingency. Freeze the decomposed-country leaf ids (US,
China, Russia; India already fixed) so the closed set is reconstructable
from the document, and add a 25 verified-entry floor alongside the
15-country bar so coverage cannot be met by tiny single subregions.

Reference LP-0020 (OSM Map Viewer) as the complementary usage layer.

Co-authored-by: Cursor <cursoragent@cursor.com>

prizes/LP-0018.md

@@ -11,6 +11,8 @@ dependencies: []
 
 This prize funds an **OpenStreetMap (OSM) data distribution system** for the Logos ecosystem. Users can browse available map regions, host map data in Logos Storage, and download verified map files with checksum guarantees.
 
+Geofabrik publishes regions as a tree: a country extract is the union of its subregions (for example the India country file contains all six India zones; the same bytes appear again in each zone file under a different CID and checksum). Regions in this system are therefore identified at a specific level (country or subregion) and the predefined set is **non-overlapping** (no region contains another) so the same geography is never hosted or counted twice. See [Appendix A.4](#a4-predefined-regions) for the region model and the closed set.
+
 The deliverable has two required parts: a **Logos Basecamp app** (region discovery, host/download workflows, checksum verification, and bulk operations) and a standalone **OSM registry module/SDK** for programmatic interaction with the on-chain registry.
 
 **Requires:**
@@ -31,16 +33,17 @@ This prize complements existing Logos sample apps (notably [LP-0017](LP-0017.md)
 
 ### Functionality
 
-- [ ] **Region discovery**: fetch the Geofabrik index and display available regions with version info.
+- [ ] **Region discovery**: fetch the Geofabrik index and display available regions with version info and their level in the region tree (country / subregion), restricted to the predefined set.
 - [ ] **Host workflow**: download PBF from Geofabrik → store to Logos Storage → register on-chain via the OSM registry LEZ program.
 - [ ] **Download workflow**: fetch from Logos Storage (if hosted) or Geofabrik (direct fallback).
 - [ ] **Checksum verification**: verify a downloaded file against Geofabrik's published MD5 checksum.
-- [ ] **Bulk host**: allow selecting multiple regions to host at once, with opt-out per region.
+- [ ] **Bulk host**: allow selecting multiple regions to host at once, with opt-out per region. Because the predefined set is a non-overlapping partition, bulk selection stays within that set; if a submission chooses to also expose non-partition regions, it must warn when a selection would host a region already contained in another selected or hosted region (parent/child overlap).
 - [ ] **Local import**: user provides a local PBF → verify checksum → store → register.
-- [ ] **Update check**: compare central versions vs registry and notify the user of available updates.
+- [ ] **Update check**: compare central versions vs registry and notify the user of available updates. Version comparison is per region entry (matched on the region path), so updating a country file and its subregions are tracked independently.
 - [ ] **On-chain registry**: an OSM registry LEZ program that:
-  - stores per-region entries with at minimum: `region`, `cid`, `source_url`, `checksum`, `version`, `hosted`, and `timestamp` (see [Appendix A.2](#a2-registry-schema-lez-program-account)),
-  - is queryable by region and by CID,
+  - stores per-region entries with at minimum: `region`, `parent`, `level`, `cid`, `source_url`, `checksum`, `version`, `hosted`, and `timestamp` (see [Appendix A.2](#a2-registry-schema-lez-program-account)),
+  - identifies each region by its Geofabrik path so that `region` is unique and its position in the tree (`parent`, `level`) is explicit,
+  - is queryable by region, by parent, and by CID,
   - supports registering multiple regions in a single batch transaction when bulk hosting.
 - [ ] **OSM registry module**: extract registry interaction logic into a self-contained module with a documented API, reusable by other Logos apps without depending on the Basecamp app itself.
 
@@ -72,6 +75,36 @@ This prize complements existing Logos sample apps (notably [LP-0017](LP-0017.md)
 - [ ] A reproducible end-to-end demo script is provided and works against a real local sequencer with `RISC0_DEV_MODE=0`.
 - [ ] A recorded video demo of the end-to-end flow is included in the submission; the recording must show terminal output (including proof generation) to confirm `RISC0_DEV_MODE=0` was active.
 
+## Adoption
+
+> These criteria measure traction attributable to a given submission for this prize: not that the system was built (that is FURPS, above), but that it is actually serving as a **decentralized distribution layer** with real, independently mirrored map data.
+>
+> The **Required** criteria below are all mandatory in addition to the FURPS criteria, and are written so that an evaluator can confirm each one directly from on-chain registry data and Geofabrik, without trusting the submitter. The **Discretionary signals** are considered in addition, per the evaluation policy that applies to all prizes (see [Terms & Conditions](../TERMS.md)); evaluators inspect account and commit histories, and volume that is clearly manufactured (fresh accounts, purchased engagement) does not count regardless of the headline number.
+
+**Required (independently verifiable):**
+
+- **Coverage.** At least **15 countries** from the predefined set (see [Appendix A.4](#a4-predefined-regions)) are covered on-chain and hosted in Logos Storage, and at least **25 total verified region entries** are covered across the set. A country counts as covered when it is a country-level entry that is registered, or a decomposed country (US, India, China, Russia) for which **at least one of its subregions** is registered. Each contributing entry must verify: the evaluator fetches the CID from Logos Storage, hashes the bytes, and confirms the hash matches Geofabrik's published MD5 for that snapshot. Entries whose stored bytes do not match Geofabrik do not count, and an unverified subregion does not make its country count. The 25-entry floor is above the 15-country minimum and forces some depth in the decomposed countries, so coverage cannot be met by decomposed countries each satisfied with a single small subregion.
+- **Redundant mirroring.** Each **covered region entry** (a country-level region, or a registered subregion of a decomposed country) is registered by **at least 3 distinct accounts**, so no single operator is the sole source for any region. This is verifiable directly from registry entries. (The *count* of distinct accounts is objective; whether those accounts are genuinely independent operators is assessed under Discretionary signals below.)
+- **Freshness.** At least **5** registered region entries have had their version advanced to a newer Geofabrik snapshot after initial registration, via the update-check flow. This is confirmable from on-chain version/timestamp history checked against Geofabrik, and demonstrates the mirrors are maintained rather than a one-time dump.
+- **Sustained activity.** Registration and re-hosting activity is spread over **at least 2 months**, verifiable from on-chain timestamps. A single burst of registrations does not qualify, however large.
+
+**Discretionary signals (considered in addition, per Terms & Conditions):**
+
+- **Operator independence.** The accounts behind the mirror counts are genuinely independent hosts with real account history, not one team spinning up accounts to satisfy the redundancy bar. Evaluators inspect on-chain and account histories.
+- **Ecosystem reuse.** At least a few independent applications or modules consume the OSM registry module/SDK to discover or fetch regions. Use of the SDK is confirmable by code inspection; whether the consuming projects are genuine and independent of the submitting team is discretionary.
+- **Community vouching.** Testimonials from people who have actually hosted or used a region (for example, on Discord and on Twitter/X), with account histories inspected.
+
+**Testnet reset / chain data loss contingency:**
+
+This prize targets a live Logos testnet. Testnets may be reset, redeployed, or replaced by a newer version, and on-chain registry data (entries, versions, timestamps) may be lost in the process. The adoption criteria above are cumulative and time-windowed, so a reset can break them through no fault of the builder. If a testnet reset or data loss occurs during an active submission, the following applies:
+
+- **The prize continues.** A reset does not disqualify in-progress work or reset a builder's eligibility to submit.
+- **All criteria are measured only on the current live chain.** Adoption is always evaluated against the testnet that is live at evaluation time. Data that existed only on a wiped chain does not count toward any criterion and will not be credited from off-chain records (explorer exports, screenshots, CI logs, or the builder's own claims): none of those are independently verifiable, which is the whole point of these criteria. A submission cannot qualify on the strength of a chain that no longer exists.
+- **The adoption clock restarts at the reset.** The 2-month sustained-activity window is measured from the later of the builder's first registration on the current chain or the most recent testnet reset. A builder is never asked to show on-chain history spanning a reset, and equally cannot carry forward history from before one. In practice this means a reset restarts the sustained-activity window from zero on the new chain.
+- **Re-hosting after a reset is expected.** Builders re-register and re-host coverage on the new chain. Because the underlying bytes are still verifiable against Geofabrik, re-establishing coverage is fast; but the sustained-activity and freshness windows genuinely begin again, since the on-chain evidence for them begins again.
+
+> **Note on usage/download metrics.** This prize deliberately does **not** set a download or retrieval count. Logos Storage is a peer-to-peer filesharing layer with no verifiable retrieval accounting, and its roadmap adds provider and downloader anonymity; a download count could only ever be a self-reported number that no third party can audit. Adoption is therefore measured by *verified, redundantly mirrored, maintained coverage* — what can be objectively confirmed — rather than by unverifiable retrieval figures.
+
 ## Scope
 
 ### In Scope
@@ -92,7 +125,7 @@ Geofabrik is the **canonical source of truth** for snapshot bytes and MD5 checks
 - Map rendering or tile server.
 - Real-time OSM synchronization (snapshots only).
 - Geocoding, routing, or navigation features.
-- Custom regions outside the predefined list (see [Appendix A.4](#a4-predefined-regions)).
+- Custom regions or arbitrary levels outside the predefined partition (see [Appendix A.4](#a4-predefined-regions)).
 - A hosted relay or backend service — registry, storage, and app logic run on the Logos stack; Geofabrik is used only as an external canonical snapshot source.
 
 ## Prize Structure
@@ -154,6 +187,8 @@ The following policies apply to all prizes (see [evaluation policies](../README.
 
 This prize targets snapshot-based distribution from Geofabrik. A follow-up prize may cover incremental updates, additional region sources, or deeper integration once built-in Logos Storage and Blockchain modules ship in Basecamp.
 
+[LP-0020: OSM Map Viewer](https://github.com/logos-co/lambda-prize/pull/82) is a complementary prize expected to land shortly after this one. It consumes the PBF snapshots distributed here (from Logos Storage and the on-chain LEZ registry) to provide offline map rendering, search, and POI discovery, turning the distributed data into an end-user experience. LP-0018 delivers verified, decentralized distribution of the map data; LP-0020 delivers usage of that data. The two are designed to fit together, with LP-0020 depending on the registry and storage layer built here.
+
 ---
 
 ## Appendix: Technical Design and Requirements
@@ -166,14 +201,14 @@ The items below mirror the main-body success criteria and scope. A submission mu
 
 **Functionality**
 
-- [ ] Region discovery from Geofabrik JSON index with version info displayed per region.
+- [ ] Region discovery from Geofabrik JSON index with version info and region level (country / subregion) displayed per region, restricted to the predefined set.
 - [ ] Host workflow: Geofabrik PBF download → Logos Storage upload → OSM registry LEZ program registration.
 - [ ] Download workflow: Logos Storage when hosted; Geofabrik direct when not.
 - [ ] MD5 checksum verification against Geofabrik-published checksums.
 - [ ] Bulk host with per-region opt-out.
 - [ ] Local PBF import with checksum verification before store and register.
 - [ ] Update check comparing Geofabrik central versions against on-chain registry entries.
-- [ ] OSM registry LEZ program: stores schema fields from [A.2](#a2-registry-schema-lez-program-account); queryable by region and CID; supports batch registration.
+- [ ] OSM registry LEZ program: stores schema fields from [A.2](#a2-registry-schema-lez-program-account) including `region` (Geofabrik path), `parent`, and `level`; queryable by region, parent, and CID; supports batch registration.
 - [ ] Standalone OSM registry module/SDK with documented API.
 
 **Usability**
@@ -244,9 +279,11 @@ The items below mirror the main-body success criteria and scope. A submission mu
 
 ```json
 {
-  "region": "berlin",
+  "region": "us/california",
+  "parent": "us",
+  "level": "subregion",
   "cid": "Qm...",
-  "source_url": "https://download.geofabrik.de/europe/germany/berlin-latest.osm.pbf",
+  "source_url": "https://download.geofabrik.de/north-america/us/california-latest.osm.pbf",
   "checksum": "md5:6485e3b66007593f36574c2bbb51c24f",
   "version": "2026-05-27",
   "hosted": true,
@@ -254,6 +291,13 @@ The items below mirror the main-body success criteria and scope. A submission mu
 }
 ```
 
+Field notes:
+
+- `region` is the region's Geofabrik path (for example `germany`, `germany/berlin`, `us/california`). It is the unique key for an entry and disambiguates a subregion from a same-named entity elsewhere in the tree.
+- `parent` is the `region` path of the containing region, or `null`/empty for a top-level (continent-level country) entry. It lets the registry and evaluators reconstruct the tree and detect parent/child overlap.
+- `level` is one of `country` (top-level national extract) or `subregion` (any Geofabrik subdivision of a country: zone, province, federal district, or state). Coverage and mirror counts are computed per entry; a country entry and a subregion entry that geographically overlap are distinct entries and must not both appear in the predefined set.
+- `source_url`, `checksum`, and `version` are taken from Geofabrik for that exact region path, so verification stays a direct comparison against the canonical source at the same level.
+
 ### A.3 Checksum verification flow
 
 1. Registry entry contains: `source_url` + `checksum`.
@@ -271,17 +315,48 @@ This blocks spoofing: an attacker cannot produce a file matching Geofabrik's pub
 
 ### A.4 Predefined regions
 
-Closed set from Geofabrik (~55 regions):
+#### A.4.1 Region model
 
-**Europe:** Germany, France, UK, Italy, Spain, Poland, Netherlands, Belgium, Switzerland, Austria, Czech Republic, Sweden, Norway, Denmark, Finland, Portugal, Greece, Ireland, Hungary, Romania, Bulgaria, Ukraine, Belarus, Russia, Turkey
+Geofabrik is a tree. Every extract exists at a level, and a parent extract is the byte-for-byte union of its children:
 
-**North America:** USA, Canada, Mexico, California, Texas, New York, Florida, Ontario, Québec
+- `country` — a national extract, e.g. `germany`, `india`, `us`.
+- `subregion` — any Geofabrik subdivision of a country (zone, province, federal district, or US state), e.g. `india/southern-zone`, `china/guangdong`, `russia/volga-fed-district`, `us/california`.
+- Some countries have no subregions in Geofabrik and exist only at `country` level, e.g. `bangladesh`, `kenya`, `nigeria`.
 
-**Asia:** Japan, China, India, South Korea, Indonesia, Thailand, Vietnam, Malaysia, Philippines, Australia
+Each region is identified by its **Geofabrik path** (the `region` field), carries its `parent` path and `level`, and resolves to one `source_url` (`https://download.geofabrik.de/<path>-latest.osm.pbf`) with a matching `.md5` checksum.
+
+**Non-overlap invariant.** No region in the predefined set is an ancestor or descendant of another region in the set. In practice this means: if a country is represented by any of its subregions, its country file is not in the set, and vice versa. This guarantees each piece of geography is hosted and counted at most once, so coverage and mirror counts in the adoption criteria are well defined and a submission cannot inflate coverage by registering a country plus its children.
+
+Partial coverage of a decomposed country is allowed: representing the United States by a chosen subset of high-demand state extracts (and not `us`) is valid; the states outside the subset are simply out of scope, not double-counted. What is not allowed is holding both a region and something it contains.
+
+A country is listed as **decomposed** (represented by subregions) when its country file is large enough that a single extract is impractical to mirror; otherwise it is listed at country level. The choice is fixed per country below so the set stays non-overlapping.
+
+#### A.4.2 Closed set
+
+Countries represented **at country level** (`level: country`, `parent: null`):
+
+**Europe:** Germany, France, United Kingdom (`great-britain`), Italy, Spain, Poland, Netherlands, Belgium, Switzerland, Austria, Czech Republic, Sweden, Norway, Denmark, Finland, Portugal, Greece, Ireland, Hungary, Romania, Bulgaria, Ukraine, Belarus, Turkey
+
+**North America:** Canada, Mexico
+
+**Asia:** Japan, South Korea, Indonesia, Thailand, Vietnam, Malaysia, Philippines, Pakistan, Bangladesh, Iran
+
+**Oceania:** Australia
 
 **South America:** Brazil, Argentina, Colombia, Peru, Chile
 
-**Africa:** South Africa, Egypt, Nigeria, Kenya, Morocco
+**Africa:** South Africa, Egypt, Nigeria, Kenya, Morocco, Ethiopia
+
+Countries represented **by subregions** (decomposed; the country file itself is **not** in the set). These are the largest extracts, where subregion granularity is more mirror-friendly and closer to how users pull data:
+
+- **United States** (`us`) -> 8 state extracts: `us/california`, `us/texas`, `us/florida`, `us/new-york`, `us/washington`, `us/illinois`, `us/georgia`, `us/pennsylvania`. `us` as a whole is never in the set.
+- **India** (`india`) -> its 6 zones: `india/central-zone`, `india/eastern-zone`, `india/north-eastern-zone`, `india/northern-zone`, `india/southern-zone`, `india/western-zone`.
+- **China** (`china`) -> 6 province extracts: `china/guangdong`, `china/jiangsu`, `china/shandong`, `china/zhejiang`, `china/sichuan`, `china/henan`.
+- **Russia** (`russia`) -> 4 federal-district extracts: `russia/central-fed-district`, `russia/northwestern-fed-district`, `russia/volga-fed-district`, `russia/siberian-fed-district`.
+
+These leaf ids are frozen: the closed set is exactly the entries listed above, so a third party can reconstruct it directly from this document. The registry stores each leaf as its own entry with `parent` set to the decomposed country (`us`, `india`, `china`, `russia`). Coverage counts hosted leaf entries, not the decomposed country as a single unit. If Geofabrik renames a leaf, this document is patched to match; the set does not drift with the index.
+
+> Rationale: the original flat list mixed `USA` with individual states (California / Texas / New York / Florida), double-counting those states' geography. Under the non-overlap rule the United States is represented by state extracts only, removing the overlap; the same rule decomposes India, China, and Russia, whose country files are too large to mirror as a single blob.
 
 ### A.5 Third-party app compatibility