fix(domain-instances): OSM IDs are flat per-type spaces; adapter constructs prefix from coordinates

[AdaWorldAPI]

Summary

Closes Codex P2 on PR #41 (now merged). Per your instruction, fresh PR for visibility.

The error

§2.6 lead paragraph claimed:

"OSM IDs are already prefix-structured (country/region/city/street/house), so the adapter is doing identity-extraction, not identity-construction"

That's factually wrong on two axes:

1. OSM IDs are NOT hierarchical. Per the OSM data model, Node / Way / Relation each have their own per-element-type flat numeric ID space. Node 100, Way 100, and Relation 100 are unrelated; IDs carry no spatial information.
2. The country/region/city/street/house hierarchy is what Nominatim constructs, not a property of OSM IDs. Relying on identity-extraction from raw OSM IDs would produce non-local or colliding NiblePath keys — the Codex P2's specific concern.

The fix

Rewrite the §2.6 lead paragraph to correctly describe:

• OSM elements use per-element-type flat numeric ID spaces (with link to the OSM data model spec).
• The adapter does identity construction, not extraction:
  • Computes the Cesium TMS quadkey from the element's coordinates (for Node/Way with geometry).
  • For Relations without coordinates: derives from member centroid OR from admin_level boundary walk.
  • Prepends the quadkey to the per-type OSM ID, yielding osm/<quadkey>/<type>/<id> as the NiblePath form.
• Pins the architectural distinction: "The quadkey IS the spatial frame; the per-type ID is the leaf inside it."

Internal consistency preserved

Surface	Status after fix
"Spatial prefix-locality" bullet — example osm/<quadkey>/way/123	unchanged — matches the corrected lead's osm/<quadkey>/<type>/<id> form
Verbatim §6 callout — "Marienplatz is_in Munich in sub-microsecond"	unchanged — Marienplatz IS routed via osm/<munich-quadkey>/way/<id>; is_in Munich IS a quadkey-prefix-containment check; mechanism stays
§3 capability matrix row "Spatial prefix routing (Cesium TMS quadkey via NiblePath)"	unchanged — already correctly named quadkey (not OSM ID) as the prefix source
Q2 coordination outcome (Cesium TMS quadkey as NiblePath)	unchanged — the runtime side's lance-graph PR #473 §2 had it right; this fix tightens the prose that explains why the outcome was correct

Verification

• cargo check --workspace --all-targets → clean (docs-only)
• PII abort-guard (word-boundary): CLEAN

Note

The error was framing-grade, not architecture-grade. The runtime session's cesium-osm-substrate-v1.md §2 (Q2 outcome) correctly specified "Cesium TMS quadkey as NiblePath prefix" — my §2.6 lead just mis-attributed the prefix source to the OSM ID structure rather than to the coordinate-derived quadkey. The corrected text now matches the Q2 design intent exactly.

https://claude.ai/code/session_01PBTGaPCSnnt6u3pjXpbLwY

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 06c15dbcb9

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Resolve way geometry before deriving quadkeys

The new spec says the adapter computes the quadkey from the element's coordinates, but in OSM only nodes carry lat/lon; ways are ordered node references and relations are member lists, as described by the linked OSM data model. In the queued ogar-from-osm-pbf path, following this literally leaves ways without a coordinate source or pushes implementers toward using the way id, so the spec should say that ways/relations first resolve member-node geometry and then derive the chosen centroid or covering tile.

Useful? React with 👍 / 👎.

[AdaWorldAPI]

Fixed in the latest commit on this branch.

The §2.6 lead paragraph's quadkey-derivation step now uses an explicit per-type bullet list that matches the OSM data model exactly:

• Node — directly from its own lat/lon (the only element type that carries coordinates)
• Way — resolve the ordered Node-references first to get the underlying lat/lon list, then centroid / covering tile
• Relation — resolve member references recursively, then centroid / covering tile or admin_level-boundary walk

Removes the implementer footgun where literal reading would have left Ways without a coordinate source. The osm/<quadkey>/<type>/<id> NiblePath form is unchanged; only the geometry-resolution sub-step was over-simplified.