Add out-of-core OpenStreetMap example (examples/osm)

[adhami3310]

Packages the planet-scale OSM demo as a proper example under examples/osm/, instead of loose files in scripts/ and a sibling ../osmium-rs checkout.

What's here

• osmium-rs/ — the native Rust crate, moved in-tree: osm-nodes (PBF → f64 columns, ~250× pyosmium; multithreaded + zlib-ng) and osm-sort (builds the Tier-3 spatial index). Build artifacts (target/) gitignored.
• ingest.py — parse a planet .pbf into f64 columns and render the out-of-core density scatter (with a memory report + zoom timings).
• viewer.py — interactive browser viewer serving xy's real WebGL client over plain HTTP; pan/zoom re-aggregate every viewport from disk.
• _pbf_split.py — PBF blob-framing helper.
• README.md — the full parse → sort → view pipeline, prerequisites, and timings.

Scope notes

• Zone-map disk cache (which the user also asked about) already shipped in Out-of-core canonical columns (disk-backed mmap store) #155 — this PR just documents and demonstrates it. Verified live: figure build over the 10.7B-node planet drops from ~51 s → 0.12 s on reopen, because the first figure() persists per-chunk statistics to a .xyzones sidecar that later runs validate (size/mtime) and reuse.
• Adjusts paths for the new location (repo root two levels up; native binaries under osmium-rs/target/release), removes hardcoded personal paths, and errors clearly if the render client bundle (built, not committed — Build the JS render client at packaging time instead of committing it #214) is missing.
• No engine/core code changes; example-only. Renders 10.7B nodes with 0 bytes RAM-resident canonical data, 172 GB on disk.

Verified

• Crate builds in the new location; osm-nodes/osm-sort binaries present.
• Ruff check/format clean repo-wide; codespell clean on new files.
• End-to-end figure build against the real 172 GB columns: 10,742,674,832 nodes, canonical_bytes = 0, 0.12 s via the zone-map cache.

[codspeed-hq]

Merging this PR will not alter performance

✅ 102 untouched benchmarks
⏩ 1 skipped benchmark¹

---

_{Comparing osm-example (fc29d4c) with main (68617fe)}

Footnotes

1. 1 benchmark was skipped, so the baseline result was used instead. If it was deleted from the codebase, click here and archive it to remove it from the performance reports. ↩

[greptile-apps]

Greptile Summary

This PR adds an out-of-core OpenStreetMap example under examples/osm/. The main changes are:

• An in-tree Rust PBF decoder and spatial sorter.
• Python ingestion and interactive viewer scripts.
• Documentation for the parse, sort, and view pipeline.
• Validation for truncated PBF files and invalid sorter arguments.
• A request-body size limit for the viewer.

Confidence Score: 5/5

This looks safe to merge.

The parser fixes cover sparse nodes and truncated input. The sorter fixes reject the reported invalid argument cases.

No additional blocking issue qualifies.

T-Rex Logs

What T-Rex did

• Observed that the pre-feature revision had no examples/osm/viewer.py and the browser request returned HTTP 404.
• Validated that after the feature, the real page renders a density chart from the generated fixture, starting with an unzoomed view.
• Demonstrated user interaction by zooming to 265% with the wheel and dragging, causing the viewport to update and the page to respond with HTTP 200.
• Confirmed browser validation finished with exit code 0 and Chromium emitted only non-fatal WebGL performance warnings.
• Collected and organized artifacts, including before/after videos and images, plus logs and a Python harness, to support verification.

_{Ran code and verified through T-Rex}

Important Files Changed

Filename	Overview
examples/osm/osmium-rs/src/lib.rs	Decodes dense and sparse OSM nodes and reports incomplete PBF blobs as errors.
examples/osm/osmium-rs/src/sort.rs	Builds the spatial index and validates grid and partition settings before processing.
examples/osm/osmium-rs/src/sort_main.rs	Parses sorter options and rejects incomplete extent arguments through the normal error path.
examples/osm/viewer.py	Serves the interactive viewer and limits declared request-body sizes.
examples/osm/ingest.py	Runs native PBF ingestion and demonstrates out-of-core rendering and memory reporting.

_{Reviews (2): Last reviewed commit: "osm-sort: parse CLI options without pani..." | Re-trigger Greptile}