docs(cesium-osm): §11 ADR-024 adoption callout — D-OSM-2 ρ-vs-reference contract#475
Merged
Merged
Conversation
…ce contract Closes the runtime-side follow-up commitment that **OGAR #39 ADR-024 § Consequences** explicitly names by reference: *"Reports ρ-vs-reference on first per-country PBF run per the runtime session's §11 follow-up commitment"*. Sibling to #474 (the codex P2 D-OSM-2 ownership-boundary fix landed by the other session). This PR is purely additive — appends a new **§11 ADR-024 adoption — palette256 + HHTL codec contract** section at the end of `cesium-osm-substrate-v1.md` without touching the existing §1-§10 or the §11 (NOT covered) section labelling (now §11 ADR-024 + §10 NOT covered before _End of plan_). ## What the new §11 pins 1. **Adoption checklist** (ADR-024's 4-step) mapped onto D-OSM-2: - Prefix = Cesium TMS quadkey `qk:<level>/<x>/<y_tms>` (Q2 ruling). - Palette domain = OSM tag-values per-tile (≤256 at zoom 21 per ADR-024 §256-ceiling escape hatches) + tile-local quantized coords (sub-cm at zoom 21). - ρ-vs-reference target ≥ 0.99 matching the `arm-discovery` aerial-codebook anchor (ρ = 0.9973 vs cosine). - Decode = const-table lookup; zero-allocation. 2. **Falsifiable adoption contract** for D-OSM-2: - Report empirical ρ on first per-country PBF run (default: Liechtenstein per §6 OQ-OSM-4). - Report per-tile palette cardinality distribution (mean / p95 / p99) — escape hatch selected from measurement. - Decode bandwidth target ≥ 10⁸/sec on AVX-512. - If ρ < 0.99 on first run, document gap before multi-country ingest (escalate to per-tile, hierarchical, or palette-64K). 3. **Cross-arc adopters table** — three shipped anchors (`arm-discovery`, `Binary16K` `_effectiveReaders`, `bgz-tensor` `WeightPalette`) + two queued adopters (`D-OSM-2`, `D-SPLAT-4` — both named in ADR-024 § Consequences). 4. **Why §11 not §3**: ADR-024 codec contract is independent of §3 carrier-shape contract (Q1 v1 fallback). The Arrow `List<Struct<key,value>>` column shape holds whether or not the tag value is palette-encoded; palette is a transparent codec underneath the column. Keeping §11 separate preserves §3's "carrier shape" framing while pinning the codec contract. ## Why a separate small PR (not bundled with #474) #474 (other session) landed the codex P2 D-OSM-2 ownership- boundary fix as a 1-line minimal edit. The §11 ADR-024 callout is purely additive (no overlap with #474's diff). Keeping them as two PRs preserves the codex-fix vs proactive-architectural-pin separation — codex reviewers can pattern-match each PR's intent without bundling. ## Companion (separate small PR — also being filed) D-SPLAT-4 in `splat-native-ultrasound-v1.md` deserves the symmetric ADR-024 adoption note (ADR-024 § Consequences names both D-OSM-2 AND D-SPLAT-4 as queued adopters). That edit ships as `claude/splat-native-adr-024-callout` since the splat-native arc has its own branch lineage and its own #471/#472 PR history. ## Test plan - [x] Docs/plan only — no source code; no build/test invoked. - [x] §11 cites ADR-024 by file:line (`OGAR/docs/ARCHITECTURAL- DECISIONS-2026-06-04.md`) + the arm-discovery ρ=0.9973 empirical anchor + bgz-tensor `WeightPalette` reference. - [x] Falsifiable contract is testable at D-OSM-2 implementation time (per-country PBF run; reported ρ + cardinality distribution + decode bandwidth). - [x] No collision with #474 (purely additive section append). - [ ] Codex re-review on this PR.
|
Warning Review limit reached
More reviews will be available in 53 minutes and 44 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 (1)
📝 WalkthroughWalkthroughThis PR adds Section 11 to the Cesium OSM substrate plan document, formally adopting ADR-024 (Palette256 + HHTL codec contract) for the D-OSM-2 component. The section specifies palette domain boundaries, empirical acceptance thresholds (ρ ≥ 0.99), required reporting metrics for the first per-country PBF ingest run, and conditional escalation or documentation requirements if compression performance falls below threshold. ChangesADR-024 Codec Contract Adoption
🎯 1 (Trivial) | ⏱️ ~3 minutes Possibly Related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 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 |
5 tasks
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.claude/plans/cesium-osm-substrate-v1.md:
- Line 319: The doc currently uses two different canonical prefix forms —
"qk:<level>/<x>/<y_tms>" and "osm/qk:<level>/<x>/<y>/<type>/<id>" — causing
incompatible parsing; pick one canonical prefix (or explicitly declare that
"qk:..." is the tile-frame prefix and "osm/qk:.../<type>/<id>" is the full
identity path), update the text to state that decision, and adjust any
references and parsing examples/regexes (e.g., anywhere that parses qk or osm/qk
tokens) to use the chosen canonical string so downstream implementers have a
single, unambiguous prefix to split on.
- Around line 320-322: Add a falsifiable coordinate-quality metric alongside tag
ρ for D-OSM-2: define and report a quantized-coordinate decode-error metric for
the "tile-local 16-bit quantized coordinates" domain (e.g., per-tile max error
and p95/p99 error in meters or an equivalent ULP budget), set acceptance
thresholds (e.g., max ≤ X meters and p95 ≤ Y meters) and require these metrics
be measured and reported in ADR-024 compliance checks (same places that measure
tag ρ and compare to the `lance-graph-arm-discovery` anchor); update the spec
text around "Identify the palette domain", "Build the palette + measure
ρ-vs-reference", and any decode/const-table sections to state the new coordinate
metric, its units, and that builds must fail if the coordinate thresholds are
not met.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 8b13973f-cb43-405a-86c1-e72054c7262d
📒 Files selected for processing (1)
.claude/plans/cesium-osm-substrate-v1.md
…on + coordinate-fidelity metric) Addresses two CodeRabbit Major findings on #475: ## Fix 1 — Prefix form unification (CR Major @ line 14) §11 step 1 used `qk:<level>/<x>/<y_tms>` while §2 Q2 declares the full identity as `osm/qk:<level>/<x>/<y>/<type>/<id>`. The two are not competing formats — the §11 form is the **tile-frame quadkey prefix portion** of the §2 Q2 form (truncated to what ADR-024 calls "the prefix" for palette purposes; §2 Q2 is the **full identity path** including namespace + element-type/ID suffix). Adds an explicit clarification noting this two-layer addressing distinction. Also clarifies that §2 Q2's bare `<y>` means `<y_tms>` — the Q3-converted Y coordinate after the OSM-XYZ → TMS ingest boundary flip. §11 spells `<y_tms>` for explicitness; §2 Q2 leaves it bare because the ingest boundary normalizes to TMS before any consumer reads the identity. Result: downstream implementers see one canonical full-identity form (§2 Q2) and one canonical tile-frame prefix form (§11) that are the same key at different layers of detail — not two incompatible prefixes to split on. ## Fix 2 — Coordinate-fidelity metric (CR Major @ lines 17 + 320-333) §11 acceptance criteria measured ρ only for tag equality. The palette domain ALSO covers tile-local 16-bit quantized coordinates (called out in step 2), but coordinate fidelity could silently regress with no falsifiable gate. Adds a **coordinate-decode-error budget** alongside tag ρ in the §11 falsifiable adoption contract: - **Coordinate fidelity** target: **max ≤ 5 cm AND p95 ≤ 1 cm at zoom 21** (tile bounds ~4 m; 16-bit quantization theoretical resolution ~0.06 mm per axis — the 5 cm / 1 cm thresholds leave ~3 orders of magnitude headroom for projection round-trip error). Report max + p95 + p99 over all decoded coordinates. - **New escape hatch** (mirrors the per-tile palette escalation pattern): 24-bit-per-axis quantization OR per-tile floating- point fallback if max budget is breached. The escalation policy now triggers on EITHER ρ < 0.99 OR coordinate-budget breach — two falsifiable gates, both reported, neither silently regressing. Also tightened step 2's "sub-cm precision" claim to the more accurate "~0.06 mm per-axis resolution at zoom 21 — sub-mm" matching the theoretical floor. ## What this PR does NOT do - No source code; docs/plan only. - Does not duplicate work from #474 (other session's D-OSM-2 ownership-boundary fix) — purely additive in §11. - Does not touch §3 (carrier-shape contract) — coordinate fidelity is a §11 codec-contract concern per the §11-vs-§3 framing the initial PR pinned. ## Test plan - [x] Docs/plan only — no source code; no build/test invoked. - [x] Both findings addressed in single commit on the open #475 branch. - [x] Prefix-form unification preserves the §2 Q2 / §11 distinction (full identity vs tile-frame prefix); no breaking change to §2 Q2's existing form. - [x] Coordinate-fidelity budget is measurable at D-OSM-2 implementation time (per-country PBF run reports max + p95 + p99). - [ ] CodeRabbit re-review on this commit.
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
Closes the runtime-side follow-up commitment that OGAR #39 ADR-024 § Consequences explicitly names by reference: "Reports ρ-vs-reference on first per-country PBF run per the runtime session's §11 follow-up commitment".
Sibling to #474 (the codex P2 D-OSM-2 ownership-boundary fix landed by the other session). This PR is purely additive — appends a new §11 ADR-024 adoption section at the end of
cesium-osm-substrate-v1.mdwithout touching the existing §1-§10. No collision with #474.What §11 pins
Adoption checklist (ADR-024's 4-step) mapped onto D-OSM-2:
qk:<level>/<x>/<y_tms>(Q2 ruling).arm-discoveryaerial-codebook anchor (ρ = 0.9973 vs cosine).Falsifiable adoption contract for D-OSM-2:
bgz-tensor::AttentionTablethroughput regime.Cross-arc adopters table — three shipped anchors + two queued:
arm-discoveryaerial codebookBinary16K_effectiveReadersbgz-tensorWeightPaletteWhy §11 not §3: ADR-024 codec contract is independent of §3 carrier-shape contract (Q1 v1 fallback). The Arrow
List<Struct<key,value>>column shape holds whether or not the tag value is palette-encoded; palette is a transparent codec underneath. Keeping §11 separate preserves §3's "carrier shape" framing.Why a separate small PR (not bundled with #474)
#474 (other session) landed the codex P2 D-OSM-2 ownership-boundary fix as a 1-line minimal edit. The §11 ADR-024 callout is purely additive (no overlap with #474's diff). Keeping them as two PRs preserves the codex-fix vs proactive-architectural-pin separation — codex reviewers can pattern-match each PR's intent without bundling.
Companion PR (filed separately)
D-SPLAT-4 in
splat-native-ultrasound-v1.mddeserves the symmetric ADR-024 adoption note (ADR-024 § Consequences names BOTH D-OSM-2 AND D-SPLAT-4 as queued adopters). That edit ships as a separate small PR on its own branch since the splat-native arc has its own #471/#472 PR lineage.Test plan
OGAR/docs/ARCHITECTURAL-DECISIONS-2026-06-04.md) + thearm-discoveryρ=0.9973 empirical anchor +bgz-tensorWeightPalettereference.Authored by session
claude/lance-graph-ontology-review-Pyry3.Summary by CodeRabbit