From 1cb25765e0b58bac5b190319331a5aaacc38cf2e Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 5 Jun 2026 12:24:10 +0000 Subject: [PATCH 1/2] =?UTF-8?q?docs(splat-native):=20D-SPLAT-4=20ADR-024?= =?UTF-8?q?=20adoption=20callout=20(symmetric=20to=20cesium-osm=20=C2=A711?= =?UTF-8?q?)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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). --- .claude/plans/splat-native-ultrasound-v1.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/.claude/plans/splat-native-ultrasound-v1.md b/.claude/plans/splat-native-ultrasound-v1.md index 3cb2bf93..b0585901 100644 --- a/.claude/plans/splat-native-ultrasound-v1.md +++ b/.claude/plans/splat-native-ultrasound-v1.md @@ -152,7 +152,16 @@ The palette codec is currently `(centroid_palette: u8, edge_weight: u8, scent: u **Compose-table size doubles** (from 256×256×1 B to 256×256×2 B) — still fits in 128 KB, still L1-resident. -**Tests:** palette compose against ground-truth Gaussians; SH-basis discrimination (cosine ≥ 0.95 against analytic SH on phantom data). +**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). +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 (the same reference used in the D-SPLAT-4 test plan below). 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 is runtime const-table; decode path is zero-allocation. Compile-time HHTL where the palette is shared across regions (e.g. global basis-ID lookup for the 256 SH signatures). + +The 256-ceiling escape hatches from ADR-024 apply directly: per-region palettes are the cheapest answer (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 is reserved for measured-cardinality escalation, not speculation. + +**Tests:** palette compose against ground-truth Gaussians; SH-basis discrimination (cosine ≥ 0.95 against analytic SH on phantom data); **NEW: empirical ρ-vs-reference reported on first FMA-region palette build (target ≥ 0.99 per ADR-024 adoption contract)**; per-region palette cardinality distribution (mean / p95 / p99) at FMA region granularity. **Gates on:** D-SPLAT-1. From 7d09f750e311724dc0aef8397f03c4e065f949ba Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 5 Jun 2026 12:30:06 +0000 Subject: [PATCH 2/2] =?UTF-8?q?docs(splat-native):=20address=20codex=20P2?= =?UTF-8?q?=20on=20#476=20(SH=20band=20notation=20=E2=84=93=3D3=20?= =?UTF-8?q?=E2=86=92=20=E2=84=93=E2=89=A43)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- .claude/plans/splat-native-ultrasound-v1.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.claude/plans/splat-native-ultrasound-v1.md b/.claude/plans/splat-native-ultrasound-v1.md index b0585901..28e37a54 100644 --- a/.claude/plans/splat-native-ultrasound-v1.md +++ b/.claude/plans/splat-native-ultrasound-v1.md @@ -154,8 +154,8 @@ The palette codec is currently `(centroid_palette: u8, edge_weight: u8, scent: u **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). +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. 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 (the same reference used in the D-SPLAT-4 test plan below). 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 is runtime const-table; decode path is zero-allocation. Compile-time HHTL where the palette is shared across regions (e.g. global basis-ID lookup for the 256 SH signatures).