feat(cesium): osm_pbf D-OSM-1 stub mirroring arcgis_pbf shape (5 unit + 7 doctests; live Q3 Y-flip helper)#214
Merged
Conversation
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.
Contributor
|
Warning Review limit reached
More reviews will be available in 59 minutes and 58 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Runtime-side companion to the lance-graph cross-workspace plan
cesium-osm-substrate-v1.md(separate PR landed in parallel). This is D-OSM-1 — the stub that mirrors the shape ofcrates/cesium/src/arcgis_pbf.rsfor the OpenStreetMap PBF ingest path.What this PR ships
crates/cesium/src/osm_pbf.rs(~470 LOC) — stub carrier types + live Q3 boundary helper.crates/cesium/src/lib.rs—pub mod osm_pbf;(registered betweenarcgis_pbfandspz).The live
xyz_to_tms_yboundary helperOSM slippy-map tile coordinates use XYZ-order (Y top-down, web standard); Cesium's
implicit_tilinguses TMS-style (Y bottom-up). These are not the same key. The boundary helper performs the one-line subtracty_tms = (2^z - 1) - y_xyzat ingest — 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 converted at ingest; runtime sees only one shape (TMS).Stub carrier types (no osmpbf dep yet)
OsmNode,OsmWay,OsmRelation,OsmPbfBlock,OsmPbfHeader— unit-struct placeholders with rich///doc comments showing the 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.decode_pbf(_bytes)returnsOsmPbfError::NotImplemented— signature pinned now so D-OSM-3 (SPO lift) and D-OSM-5 (splat-fit-geo) can reference it without waiting on D-OSM-2 wiring.Why no real
osmpbfdep yetosmpbfv0.4 (b-r-u) 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 anosmfeature flag on the cesium crate. This PR keeps thendarrayworkspace compile cost unchanged until that gate fires.Test plan
cargo fmt -p cesium— clean.cargo test -p cesium --lib osm_pbf— 5/5 unit tests pass (Y-flip zoom 0/1/10 + idempotency over zoom 0-20 + stub-returns-error guard).cargo test -p cesium --doc osm_pbf— 7/7 doctests pass.osmpbfv0.4 dependency and implementsdecode_pbf.Pre-existing CI block on master (NOT introduced by this PR)
Running
cargo clippy -p cesium --all-targets -- -D warningson the merge target (origin/masterate2ec430) without my changes surfaces 9 pre-existing errors:crates/cesium/src/fixtures.rs:412-415— 4 ×assertions_on_constants(Rust 1.95 lint upgrade; needsconst { 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 — fixes are trivial (wrap with
const { … }for fixtures, audit two lines into_cam_soa.rs:518-519).Q1/Q2/Q3 rulings preserved at the wire boundary
Per lance-graph
cesium-osm-substrate-v1.md §2coordination outcome (locked 2026-06-05):Vec<(Box<str>, Box<str>)>; migration note flags Q1 (c) Tag-as-Class target.qk_tms_path: [u8; 24]on each carrier; encoded asqk:<level>/<x>/<y_tms>ASCII bytes; matchesimplicit_tiling.rssubtree shape.xyz_to_tms_yis the live boundary helper; pinned at ingest perI-LEGACY-API-FEATURE-GATED.What's NOT in this PR
osmpbfdependency (D-OSM-2).Cross-references
.claude/plans/cesium-osm-substrate-v1.mdsplat-native-ultrasound-v1.md(D-SPLAT-1Gaussian3Dreused in D-OSM-5)Cross-PR coordination
This is one of two coordinated runtime-side PRs for the cesium-osm-substrate-v1 arc. OGAR session has the green light to file their docs PR after these merge so they can cite
D-OSM-1..7by ID. The OGAR docs PR will extendDOMAIN-INSTANCES.md §2.6(geospatial as 6th domain instance) andRDF-OWL-ALIGNMENT.md §10 Phase 2c(ogar-from-osm-pbfadapter sequencing).lance-graphclaude/cesium-osm-substrate-v1ndarrayclaude/cesium-osm-substrate-v1arcgis_pbf.rsshape + livexyz_to_tms_yQ3 boundary helper (5 unit + 7 doctests pass)OGARDOMAIN-INSTANCES §2.6+RDF-OWL-ALIGNMENT §10 Phase 2c— cites D-OSM-* by IDTriggered by user feasibility question on OpenStreetMap × Cesium × Gaussian-splat coupling.
Authored by session
claude/lance-graph-ontology-review-Pyry3.