Commit 9aa71f8
committed
feat(cesium): osm_pbf D-OSM-1 stub mirroring arcgis_pbf shape
Companion to lance-graph cross-workspace plan
`cesium-osm-substrate-v1.md` (filed in parallel PR on lance-graph).
This is **D-OSM-1** — the runtime-side stub that mirrors the shape of
`arcgis_pbf.rs` (428 LOC) for the OpenStreetMap ingest path.
## What this PR ships
- `crates/cesium/src/osm_pbf.rs` (~470 LOC, mostly doc comments + stubs)
- **Live `xyz_to_tms_y` boundary helper** (Q3 ruling from the
lance-graph plan §2): one-line subtract that converts OSM-XYZ
slippy-map Y coordinates to Cesium-TMS convention. This is the
ONLY Y-axis conversion point in the OSM ingest pipeline; pinning
it here ensures D-OSM-2 cannot regress it accidentally. Per
`I-LEGACY-API-FEATURE-GATED` — wire-format-vs-runtime boundary is
converted at ingest; runtime sees only one shape (TMS).
- **Stub carrier types**: `OsmNode`, `OsmWay`, `OsmRelation`,
`OsmPbfBlock`, `OsmPbfHeader` — unit-struct placeholders with
rich doc comments showing intended Q1 (b) v1-fallback shape
(`tags: Vec<(Box<str>, Box<str>)>`) that migrates to Q1 (c)
Tag-as-Class identity in a follow-up sprint.
- **Stub `decode_pbf`** returning `OsmPbfError::NotImplemented`.
The signature is pinned now so D-OSM-3 (SPO lift) and D-OSM-5
(splat-fit-geo) can reference it without waiting on D-OSM-2
(osmpbf v0.4 wiring).
- **5 unit tests** + **7 doctests** all pass; covers the live
boundary helper completely (zoom 0/1/10 + idempotency over
zoom 0-20 + stub-returns-error guard).
- `crates/cesium/src/lib.rs` — `pub mod osm_pbf;` (registered between
`arcgis_pbf` and `spz`, following the existing alphabetical group).
## Why no real osmpbf dep yet
The `osmpbf` v0.4 (b-r-u) crate is the only production-grade Rust OSM
PBF reader (multi-year stable, lazy-decoded, parallelized). D-OSM-2
wires it as a default-on dep behind a `osm` feature flag on the
cesium crate. This PR keeps the `ndarray` workspace compile cost
unchanged until that gate fires.
## Q1/Q2/Q3 rulings preserved at the wire boundary
Per `cesium-osm-substrate-v1.md §2` coordination outcome (locked
2026-06-05 with OGAR session):
- **Q1** (tags → IR): doc-commented carrier shows v1 (b) `Vec<(Box<str>,
Box<str>)>` Arrow-list-compatible; doc note flags Q1 (c) Tag-as-Class
migration target for follow-up sprint.
- **Q2** (NiblePath): `qk_tms_path: [u8; 24]` field on each carrier;
encoded as `qk:<level>/<x>/<y_tms>` ASCII bytes; matches Cesium
`implicit_tiling` + `sse` + `hlod` subtree shape.
- **Q3** (Y-axis): `xyz_to_tms_y` is the live boundary helper. Pinned
at ingest per `I-LEGACY-API-FEATURE-GATED`.
## Test plan
- [x] `cargo fmt -p cesium` — clean.
- [x] `cargo test -p cesium --lib osm_pbf` — 5/5 unit tests pass.
- [x] `cargo test -p cesium --doc osm_pbf` — 7/7 doctests pass.
- [x] `cargo clippy -p cesium --all-targets -- -D warnings` on my
file — zero new warnings introduced.
- [ ] D-OSM-2 PR wires `osmpbf` v0.4 dependency and implements
`decode_pbf` (separate PR, P1 sprint 1-2).
## Pre-existing master state (NOT introduced here)
Per `agent-cargo-hygiene.md` the Opus orchestrator runs gates.
Running `cargo clippy -p cesium --all-targets -- -D warnings` on
the merge target (`origin/master` at `e2ec430`) **without my
changes** surfaces 9 pre-existing errors:
- `crates/cesium/src/fixtures.rs:412-415` — 4 ×
`assertions_on_constants` (Rust 1.95 lint; needs `const { assert!(..)
}` wrapping).
- `crates/cesium/src/to_cam_soa.rs:518-519` — 5 × arithmetic-side-
effects (`identity_op` / `always returns zero`).
These predate this PR and are unrelated to OSM work. They will fail
CI for any cesium PR until cleared. **Recommend a separate cleanup PR
fixes these in master**; happy to file one as a follow-up if desired.
## Cross-references
- **Lance-graph plan** (canonical, parallel PR):
`.claude/plans/cesium-osm-substrate-v1.md` — D-OSM-1..7 + Q1/Q2/Q3
rulings + cross-arc reuse table.
- **Splat-native sibling**: D-SPLAT-1 `Gaussian3D` carrier + D-SPLAT-2
SIMD ops + D-SPLAT-3 `SplatBatch` SoA + D-SPLAT-12 `splat-render`
all reused verbatim in D-OSM-5/6 (substrate-reuse payoff).
- **OGAR coordination**: docs PR (`DOMAIN-INSTANCES.md §2.6` +
`RDF-OWL-ALIGNMENT.md §10 Phase 2c`) queued behind the lance-graph
PR so they cite D-OSM-1..7 by ID.1 parent e2ec430 commit 9aa71f8
2 files changed
Lines changed: 435 additions & 0 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
48 | 48 | | |
49 | 49 | | |
50 | 50 | | |
| 51 | + | |
51 | 52 | | |
52 | 53 | | |
53 | 54 | | |
| |||
0 commit comments