osm: migrate the cockpit key V1→V3, verified in a browser against the real slab - #109
Merged
Merged
Conversation
The OSM substrate is already plugged into OGAR USB-style: socket in lance_graph_contract::hotplug, authority in ogar_vocab::geo_actions, bridge via ogar_osm::plug_in, and the device is osm-soa-bake::capability with a real dispatch arm per capability. Six capabilities are declared on osm_node/osm_way, and two of them are things this endpoint already touches: locate_tile IS slab.tile_range, and project_fields is the masked projection. Three consequences, recorded so a future session does not re-derive them: q2 must not declare its own HOT_PLUG. GEO_EXPECTED_EXECUTORS is ["osm-soa-bake"] and resolve_hotplug checks the consumer name, so a plug from cockpit-server earns UnexpectedConsumer by design. q2 calls an already-activated device; it is not a second device. Phase 1 needs no rework. Calling slab.tile_range directly is explicitly sanctioned by capability.rs's own module doc -- the arms exist to make the registration falsifiable, not to be a mandatory call path. project_fields is a real gap, and it is the authorization one. The endpoint returns decoded values with no mask; the declared capability is surface-intersect-role and fail-closed, meaning an unauthorised position is absent from the response rather than hidden by the caller. Moot for a local cockpit, not moot for a deployment. Filed as a Phase 4 addendum with the honest caveat that it needs a role source first -- until then the endpoint should be described as unauthenticated rather than implying a mask exists.
…strate The cockpit's displayed address and the key RowSlab sorts rows by are now the same key. They were not before: osm_tiles carried its own 3-tier, z=24, un-flipped Morton key while the slab is keyed 4-tier, z=32, Cesium-TMS-flipped. Every tier differed at every point tested -- Berlin HEEL 0x624b vs 0xc8e1 -- so this was a different key, not a coarser one. Done as a real TDD loop, since the environment can now link the test binary (dropping debuginfo was what unblocked it): RED hhtl_agrees_with_the_v3_substrate_oracle failed 25163 vs 51425 GREEN 14/14 osm tests after the migration The test asserts equality against osm_soa_bake::tms::point_to_tiers -- the implementation the slab is actually keyed on -- rather than asserting the key "has four tiers", which would pass against a wrong key. Implementation is mostly deletion. The local Mercator formula, the 24-bit Morton interleave/deinterleave and the depth constant are now delegations to osm_soa_bake::tms. Two implementations of one projection is precisely how the display address and the row key drifted apart, so the duplicate is gone rather than widened. Two subtleties worth keeping: - The TMS flip must happen at the tile's own zoom and THEN be left-aligned. xyz_to_tms_y is 2^z-1-y, so flipping at z and shifting by 32-z yields the minimum TMS row of the tile's z=32 range, which is the common Morton prefix. Shifting first and flipping at 32 picks the opposite corner and breaks the prefix property. - Reading the bytes LEAF occupies as a tier, rather than as the head of the old family:u24, IS the V3 content-blind reinterpretation. TEST CHANGES -- two pre-existing tests encoded the V1 depth and were re-pinned, not silently widened: - hhtl_roundtrips_to_the_tile: z=24/3-tier/48-bit -> z=32/4-tier/64-bit, and it now un-flips the recovered row before comparing. It also asserts the stored row is genuinely flipped, so the test fails if tile_to_hhtl ever stops applying the flip. - over_depth_zoom_folds_to_its_native_ancestor: over-depth begins at 33, not 25. It now also asserts z=25 is NOT folded, which the V1 form did. - coarse_zoom_lives_in_heel_not_twig: strengthened to cover LEAF. Panel gains a fourth tier cell; the overlay JS was re-checked with node --check. The key-space warning in osm_features.rs was rewritten rather than deleted -- it records why the two keys once differed, which is the reason the equality test exists. Verification: 14/14 osm tests green; 79/80 for the whole crate. The single failure, osint_gotham::dual_use_facets_pack_into_the_value_tenant, was confirmed pre-existing by stashing this change and re-running it on main's state -- it fails identically there and touches nothing in this diff.
…e route choices The POC gate is passed. q2-cockpit was run against the real 2.5M-row Berlin slab and /osm loaded in headless chromium: 0 markers and 0 fetches before the toggle, 177,963 markers across 73,130 distinct positions after, no JS errors, and the panel reporting HEEL 0xc8e1 -- the V3 oracle value the Phase-3 falsifier asserts, now observed in a browser rather than a test. The run is hermetic (every non-localhost request aborted), so it also proves the overlay renders independently of the external basemap. The run found a real defect that tests had not: the row cap is spatially biased. MAX_FEATURES_PER_TILE is applied as take(5000) over a Morton-ordered range, so a truncated tile returns a spatially contiguous prefix -- a sub-quadrant -- rather than a sample. Measured: a capped tile covers 99.9% of its width but only 50.0% of its height, while a control tile under the cap covers 100%/100%. The counts were honest; the shape of what came back was not, and a count cannot convey that. Filed with the fix (stride-sample) and its falsifier, deliberately not applied here since it changes a shipped endpoint's behaviour and deserves its own test. Also documents every route alternative that is deliberately kept rather than removed, with which arm is wired and what switching would cause: the three /api/osm/* routes (locate is wired, tile is kept for non-map callers), direct tile_range vs the capability arm (direct is sanctioned by the capability module's own doc; q2 must not plug in or it earns UnexpectedConsumer), hand decode vs project_fields (the one with a real consequence -- the endpoint is currently unauthenticated), local slab vs S3 hydrate, and the two basemap skins (whose toggle also carries attribution, which is a licensing requirement).
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (4)
📝 WalkthroughWalkthroughThe OSM cockpit now uses substrate-backed four-tier HHTL addressing at native depth 32. The UI displays the new LEAF tier, and documentation records shared V3 keys, browser verification, oracle testing, and OGAR integration details. ChangesOSM V3 migration
Estimated code review effort: 3 (Moderate) | ~20 minutes Possibly related PRs
Suggested reviewers: Poem
✨ Finishing Touches📝 Generate docstrings
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 |
Bugbot couldn't run - usage limit reachedBugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit. A user or team admin can review and increase usage limits in the Cursor dashboard. (requestId: serverGenReqId_482b5f03-3f5c-4f5a-b5a3-f887adff6a89) |
AdaWorldAPI
marked this pull request as ready for review
August 10, 2026 23:20
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
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.
Follow-on to #108 (merged). That PR wired the endpoint and overlay and scoped the V1→V3 key gap; this one closes it and clears the gate #108 was explicitly draft on — the browser load against a real slab.
1. The V3 migration, as a real red-then-green
#108 said the falsifier was written but deliberately not committed, because this box could not link
cockpit-serverand shipping an unverifiable coordinate-key migration was the wrong trade. That constraint turned out to bedebuginfo=2, not disk volume — building withCARGO_PROFILE_DEV_DEBUG=0links a 150 MB binary instead of 2.2 GB, and the test binary runs.So the loop ran honestly:
25163/51425are0x624b/0xc8e1— the values the earlier out-of-crate probe predicted, now observed inside q2.The implementation is mostly deletion: the local Mercator formula, the 24-bit Morton pair and the depth constant become delegations to
osm_soa_bake::tms. Two implementations of one projection is how the display address and the row key drifted apart; the duplicate is gone rather than widened.Two subtleties kept in comments because they are easy to get wrong:
xyz_to_tms_yis2^z-1-y, so flipping atzand shifting by32-zyields the minimum TMS row of the tile's z=32 range — the common Morton prefix. Shifting first and flipping at 32 picks the opposite corner and breaks the prefix property.LEAFoccupies as a tier, rather than as the head of the oldfamily:u24, is the V3 content-blind reinterpretation.Test changes are re-pins, not silent widenings — two pre-existing tests encoded the V1 depth.
hhtl_roundtrips_to_the_tilenow un-flips before comparing and asserts the row is genuinely flipped (so it fails if the flip is ever dropped);over_depth_zoom_folds_to_its_native_ancestormoves to z=33 and additionally asserts z=25 is not folded;coarse_zoom_lives_in_heel_not_twiggained LEAF.2. The browser load — #108's gate, passed
Hermetic — every non-localhost request aborted, which also proves the overlay renders independently of the external basemap.
0xc8e13. A defect the browser found that the tests could not
Markers clump into a corner of each dense tile. Placement is faithful — the cap is spatially biased:
take(5000)over a Morton-ordered range returns a spatially contiguous prefix (a sub-quadrant), not a sample. The control tile is what isolates the cause to truncation rather than coordinate math.total/returnedwere honest; the shape of the result was not, and a count cannot convey that.Filed with its fix and falsifier, deliberately not applied here — it changes a shipped endpoint's behaviour and deserves its own red-then-green, which the measurement above now makes automatable.
4. Route choices documented, nothing removed
Every alternative arm is recorded with which is wired, why, and what switching would cause: the three
/api/osm/*routes; directtile_rangevs the capability arm; hand-decode vsproject_fields; local slab vs S3 hydrate; the two basemap skins. Two worth a reviewer's eye:project_fieldsis a real gap. The declared capability issurface ∩ role, fail-closed. The current arm means the endpoint is effectively unauthenticated — fine locally, not fine deployed. It needs a role source first, so the honest posture is to say so rather than imply a mask exists.HOT_PLUG.GEO_EXPECTED_EXECUTORS = ["osm-soa-bake"], so a plug fromcockpit-serverearnsUnexpectedConsumerby design. q2 calls an already-activated device; it is not a second device.Verification status — honest
osint_gotham::dual_use_facets_pack_into_the_value_tenant) was confirmed pre-existing by stashing this change and re-running against main's state — it fails identically there and references nothing in this diff. Worth attention independently.cargo xtask verify --skip-hub-buildstill not run — the workspace-wide build remains beyond this box.Draft per convention; the gate #108 was waiting on is now closed, so this can go ready as-is.
Generated by Claude Code
Summary by CodeRabbit
New Features
Bug Fixes