docs(splat-native): D-SPLAT-4 ADR-024 adoption callout (symmetric to cesium-osm §11)#476
Conversation
…cesium-osm §11) OGAR #39 ADR-024 (Palette256 + HHTL codec — universal compression primitive) § Consequences names BOTH **D-OSM-2** (geographic adopter) AND **D-SPLAT-4** (anatomical / volumetric adopter) as queued ADR-024 adopters. The geographic side already landed its adoption note in `cesium-osm-substrate-v1.md §11` (PR #475). This PR ships the symmetric anatomical-side adoption note for D-SPLAT-4 so the cross-arc references resolve. ## What this PR ships Inline ADR-024 adoption paragraph + amended test plan on D-SPLAT-4 in `splat-native-ultrasound-v1.md` §3. Single-file edit; no other sections touched. The new adoption note maps ADR-024's four-step checklist onto D-SPLAT-4 specifics: 1. **Prefix** = FMA NiblePath + SH basis-id (per-region spatial frame). 2. **Palette domain** = quantized SH coefficients (16 coeffs at ℓ=3) clustered per FMA region; per-region palette captures dominant tissue echo signatures (planar fascia / spherical organ surfaces / Doppler-flow vascular). 3. **ρ-vs-reference target ≥ 0.99** matching the `lance-graph-arm- discovery` aerial-codebook empirical anchor (ρ = 0.9973 vs cosine). Reference = analytic SH evaluation at the same view direction. Report empirical ρ on the **first FMA-region palette build** (default region: femur cortical bone — smallest tractable corpus; cf. OGAR PR #30 §6 FMA-bones litmus). 4. **Decode = const-table lookup**; per-region SH palette runtime const-table; zero-allocation; compile-time HHTL where the palette is shared across regions (global basis-ID lookup for the 256 SH signatures). The 256-ceiling escape hatches from ADR-024 are mapped: - **Per-region palettes** (cheapest) — different FMA region, different 256 SH-signature entries. - **Hierarchical palettes** (coarser at OrganSystem level, finer per Bone leaf) mirror the SH ℓ=0/ℓ=1 vs ℓ=2/ℓ=3 split. - **Palette-64K** reserved for measured-cardinality escalation. ## Amended test plan The existing D-SPLAT-4 test plan keeps its two tests (palette compose vs ground-truth Gaussians; SH-basis discrimination cosine ≥ 0.95 vs analytic SH on phantom data). The ADR-024 adoption adds: - **NEW**: empirical ρ-vs-reference reported on first FMA-region palette build (target ≥ 0.99). - **NEW**: per-region palette cardinality distribution (mean / p95 / p99) at FMA-region granularity — escape-hatch selection from measurement, not speculation. ## Cross-references - **ADR-024**: `OGAR/docs/ARCHITECTURAL-DECISIONS-2026-06-04.md § ADR-024` (OGAR PR #39, merged 2026-06-05). The § Consequences names both D-OSM-2 and D-SPLAT-4 as queued adopters. - **Geographic-side companion**: `cesium-osm-substrate-v1.md §11` (lance-graph PR #475). Same four-step adoption mapping with Cesium TMS quadkey + per-tile OSM tag palette specifics. - **Empirical anchor**: `lance-graph-arm-discovery` aerial codebook ρ = 0.9973 vs cosine — the FINDING-grade floor that new ADR-024 adopters target (≥ 0.99). ## Test plan - [x] Docs/plan only — no source code; no build/test invoked. - [x] Single-file edit; no governance-file churn (the D-SPLAT-4 STATUS_BOARD row + INTEGRATION_PLANS entry don't change — this is a clarification of an existing deliverable's acceptance criteria, not a new deliverable). - [x] Symmetric to PR #475 (cesium-osm §11 ADR-024 adoption); same four-step mapping pattern. - [x] D-SPLAT-4 existing tests preserved; ADR-024 adds ρ-vs- reference + cardinality distribution as NEW test requirements. - [ ] Codex review on this PR (light — single-paragraph addition).
|
Warning Review limit reached
More reviews will be available in 52 minutes and 42 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)
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 |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1cb25765e0
ℹ️ 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".
| **ADR-024 adoption (palette256 + HHTL codec, OGAR #39).** D-SPLAT-4 is named in `OGAR/docs/ARCHITECTURAL-DECISIONS-2026-06-04.md § ADR-024 Consequences` as one of the two queued ADR-024 adopters (paired with D-OSM-2 — see `cesium-osm-substrate-v1.md §11` for the geographic-side adoption note). Mapping ADR-024's four-step adoption checklist onto D-SPLAT-4: | ||
|
|
||
| 1. **Prefix.** FMA NiblePath + SH basis-id — the per-region spatial frame (FMA class identity within the atlas + ℓ=3 SH basis index). | ||
| 2. **Palette domain.** Quantized SH coefficients (16 coeffs at ℓ=3) clustered per FMA region. Per-region palette captures dominant tissue echo signatures (planar fascia / spherical organ surfaces / Doppler-flow vascular). |
There was a problem hiding this comment.
This adoption checklist describes “16 coeffs at ℓ=3”, but a single SH band at ℓ=3 has 2ℓ+1 = 7 coefficients; the 16-column carrier described earlier in this plan is for all bands through ℓ≤3. As written, this can send the D-SPLAT-4 implementer toward the wrong palette cardinality/basis layout, so the checklist should say ℓ≤3 if it intends the existing 16-coefficient representation.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Addressed in commit 7d09f750 (pushed to the same PR branch after the codex review of 1cb25765). The §11 adoption-checklist now reads:
1. **Prefix.** FMA NiblePath + SH basis-id — the per-region spatial frame
(FMA class identity within the atlas + SH basis index spanning the
ℓ≤3 carrier).
2. **Palette domain.** Quantized SH coefficients (16 coefficients
spanning ℓ≤3 — degree 0: 1, degree 1: 3, degree 2: 5, degree 3: 7 —
totaling 16, matching the §3 D-SPLAT-1 carrier shape) clustered per
FMA region. …
The expanded form mirrors the §0 executive-summary wording at line 23 ("spherical harmonics, ℓ≤3") and pins the 16-coefficient count to §3 D-SPLAT-1's carrier shape as the single source of truth — so a D-SPLAT-4 implementer is directed to the canonical 16-column carrier rather than a single ℓ=3 band's 7 coefficients.
Pre-existing ℓ=3 shorthand at lines 72 / 192 / 438 is left alone (out of this PR's scope; would need its own normalization sweep).
Closing — fix is on the branch tip awaiting codex re-review.
…ℓ≤3) Codex P2 finding on #476: my added text said "16 coeffs at ℓ=3" but a single SH band at ℓ=3 has 2ℓ+1 = 7 coefficients. The 16-coefficient carrier described in §3 D-SPLAT-1 is for all bands THROUGH ℓ≤3 (1 + 3 + 5 + 7 = 16). The "ℓ=3" shorthand could send a D-SPLAT-4 implementer toward the wrong palette cardinality / basis layout. ## Fix - Step 1 prefix: "SH basis index spanning the ℓ≤3 carrier" (was "ℓ=3 SH basis index"). - Step 2 palette domain: "16 coefficients spanning ℓ≤3 — degree 0: 1, degree 1: 3, degree 2: 5, degree 3: 7 — totaling 16, matching the §3 D-SPLAT-1 carrier shape" (was "16 coeffs at ℓ=3"). The expanded form mirrors the §0 executive summary line 23 wording "(spherical harmonics, ℓ≤3)" and pins the 16-coefficient count to a single source of truth via the cross-reference to §3 D-SPLAT-1. ## What this PR does NOT do - Does not touch pre-existing "ℓ=3" shorthand elsewhere in the plan (lines 72, 192, 438). Those use "ℓ=3" as informal shorthand for "up to degree ℓ=3" — common convention; out of scope for this fix. If the codex flags those as a follow-up, a separate normalization pass would touch them all together. ## Test plan - [x] Docs/plan only — no source code; no build/test invoked. - [x] Fix scoped to lines I added in #476 (157-158); does not modify pre-existing carrier-shape declarations elsewhere. - [x] Cross-references §3 D-SPLAT-1 carrier shape as the single source of truth for the 16-coefficient layout. - [ ] Codex re-review on this commit.
2 participants
Summary
Symmetric companion to #475 (cesium-osm §11 ADR-024 adoption). OGAR #39 ADR-024 § Consequences names BOTH D-OSM-2 (geographic adopter) AND D-SPLAT-4 (anatomical / volumetric adopter) as the queued ADR-024 adopters. The geographic side already landed its adoption note (#475); this PR ships the anatomical side so the cross-arc references resolve.
Single-file edit. Adds an ADR-024 adoption paragraph + amends D-SPLAT-4's test plan with ρ-vs-reference + cardinality distribution requirements. No section reordering, no governance churn (D-SPLAT-4 is an existing deliverable getting acceptance-criteria clarification, not a new deliverable).
What §3 D-SPLAT-4 now pins
The new adoption paragraph maps ADR-024's four-step checklist onto D-SPLAT-4:
lance-graph-arm-discoveryaerial-codebook empirical anchor (ρ = 0.9973 vs cosine). Reference = analytic SH evaluation at same view direction. Report empirical ρ on first FMA-region palette build (default region: femur cortical bone — cf. OGAR PR fix(.claude): array_struct.rs DROP → 🔀 EXTRACT (35 SIMD dispatch calls are P1) #30 §6 FMA-bones litmus).256-ceiling escape hatches mapped:
Amended test plan
The existing D-SPLAT-4 test plan keeps its two tests (palette compose vs ground-truth Gaussians; SH-basis discrimination cosine ≥ 0.95 vs analytic SH on phantom data). The ADR-024 adoption adds:
Cross-references
OGAR/docs/ARCHITECTURAL-DECISIONS-2026-06-04.md § ADR-024(OGAR PR Claude/unified query planner a w8ax #39, merged 2026-06-05). The § Consequences names both D-OSM-2 and D-SPLAT-4 as queued adopters.cesium-osm-substrate-v1.md §11(lance-graph PR docs(cesium-osm): §11 ADR-024 adoption callout — D-OSM-2 ρ-vs-reference contract #475). Same four-step adoption mapping with Cesium TMS quadkey + per-tile OSM tag palette specifics.lance-graph-arm-discoveryaerial codebook ρ = 0.9973 vs cosine — the FINDING-grade floor that new ADR-024 adopters target (≥ 0.99).Test plan
Authored by session
claude/lance-graph-ontology-review-Pyry3.