Skip to content

Commit 110dd3b

Browse files
committed
fix(adr-025): correct the LOD depth formula — n = 16^r (4×4), not 4-ary
Closes Codex P2 on PR #44 (now merged). # The error ADR-025 §2 said sample size "n ≈ 16^r for a 4-ary radix pyramid." That is internally inconsistent: a 4-ary pyramid grows as n = 4^r, and the cited level formula r* = ⌈log₄(C/τ)⌉ only follows from n = 16^r. As written, an implementer of D-JC-PREDICT-LOD building against the documented 4-ary pyramid would pick a level half as deep as needed and leave the predicted error above tolerance. The runtime session's original numbers were actually self-consistent on n = 16^r (it gave n^{-1/2} = 4^{-r} and r* = ⌈log₄(C/τ)⌉, which all agree). The only slip was my mislabeling the branching as "4-ary" — the pyramid increases resolution ×4 in BOTH x and y per hop, so 4 × 4 = 16 samples per level. # The fix Rewrite §2 with an explicit, self-checking derivation: n = b^r predicted_error_L = C · n^{-1/2} = C · b^{-r/2} predicted_error_L < τ ⟹ r* = ⌈2·log_b(C/τ)⌉ (general) helix pyramid ships b = 16 (×4 per axis = 4 × 4) ⟹ n = 16^r, n^{-1/2} = 4^{-r} ⟹ r* = ⌈2·log_16(C/τ)⌉ = ⌈log₄(C/τ)⌉ (canonical anchor) The canonical formula r* = ⌈log₄(C/τ)⌉ and the "5-12 hop" range are preserved (the §Consequences line now annotates it as the b = 16 reduction of r* = ⌈2·log_b(C/τ)⌉). The "4-ary radix pyramid" label is removed. # Implementer note added The §2 block now carries an explicit warning: build the level formula on the pyramid's true per-level SAMPLE growth (n = 16^r), not its per-axis fan-out (×4). Pairing the ⌈log₄⌉ pick with a pyramid that actually grows only n = 4^r selects a level half as deep as that pyramid needs (a 4-ary pyramid needs ⌈log₂(C/τ)⌉, since log₂ = 2·log₄) and leaves the error above tolerance — exactly the failure mode Codex flagged. # Review Numerically re-derived and verified: - 2·log_16(C/τ) == ⌈log₄(C/τ)⌉ across C/τ ∈ {1024, 4096, 1e5, 1.67e7} - n^{-1/2} == 4^{-r} at b = 16 - footgun direction: applying ⌈log₄⌉ to a 4-ary pyramid picks exactly half the needed depth (ratio 0.50 vs ⌈log₂⌉) — matches Codex's "half as deep as needed" - 5-12 hop band (b=16): r*=5 ⇔ C/τ~1024, r*=12 ⇔ C/τ~1.68e7 No "4-ary" mislabel remains in the doc. PII abort-guard (word-boundary): CLEAN. cargo check --workspace --all-targets: clean (docs-only). https://claude.ai/code/session_01PBTGaPCSnnt6u3pjXpbLwY
1 parent a806b87 commit 110dd3b

1 file changed

Lines changed: 26 additions & 9 deletions

File tree

docs/ARCHITECTURAL-DECISIONS-2026-06-04.md

Lines changed: 26 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1427,13 +1427,29 @@ to pick its work, with zero data-dependent branches:
14271427
NiblePath arithmetic; no float-rounding daylight between them.
14281428

14291429
2. **Jirak says which level L the cheap path will succeed at.**
1430-
For the LOD pyramid:
1431-
`n` = current sample size at level L (e.g. n ≈ 16^r for a
1432-
4-ary radix pyramid)
1433-
`predicted_error_L = C · n^{-1/2}` (L^q regime, which the
1434-
Σ-sandwich Mahalanobis distance lives in)
1435-
`r* = ⌈log₄(C/τ)⌉` for clinical tolerance τ — closed-form,
1430+
For the LOD pyramid, sample size grows by a fixed branching factor
1431+
`b` per hop-radius increment: `n = b^r`. Then:
1432+
`predicted_error_L = C · n^{-1/2} = C · b^{-r/2}`
1433+
(L^q regime, which the Σ-sandwich Mahalanobis distance lives in).
1434+
Solving `predicted_error_L < τ` for the smallest accepting level:
1435+
`C · b^{-r/2} < τ ⟹ b^{r/2} > C/τ ⟹ r > 2·log_b(C/τ)`
1436+
**`r* = ⌈2·log_b(C/τ)⌉`** for clinical tolerance τ — closed-form,
14361437
evaluated once per task class.
1438+
The helix pyramid ships **`b = 16`** (16-way per-hop sample growth
1439+
— the pyramid increases resolution ×4 in **both** x and y per hop,
1440+
so `4 × 4 = 16` samples per level; per the runtime session's
1441+
helix-pyramid spec), so `n = 16^r`, `n^{-1/2} = 4^{-r}`, and the
1442+
general formula reduces to the canonical anchor:
1443+
`r* = ⌈2·log_16(C/τ)⌉ = ⌈log₄(C/τ)⌉`.
1444+
**Implementer note for `D-JC-PREDICT-LOD`:** build the level
1445+
formula on the pyramid's true per-level *sample* growth, not its
1446+
per-axis fan-out. Here the ×4 per-axis fan-out gives `n = 16^r`
1447+
(`= 4 × 4` per level) → `r* = ⌈log₄(C/τ)⌉`. The trap Codex flagged:
1448+
pairing that `⌈log₄⌉` pick with a pyramid that actually grows only
1449+
`n = 4^r` selects a level **half as deep as that pyramid needs**
1450+
a 4-ary pyramid needs `r* = ⌈log₂(C/τ)⌉` (since `log₂ = 2·log₄`) —
1451+
and so leaves the predicted error above tolerance. Verify the real
1452+
`b` before wiring the formula.
14371453
No per-frame probing; the LOD pick is `r*` directly.
14381454

14391455
3. **HHTL routes the prefix at the picked level.**
@@ -1520,9 +1536,10 @@ ADR-024 → §11 callouts in PR #475 + PR #476).
15201536
- **Cesium tileset `bounding_volume` becomes a derived field** for
15211537
helix+HHTL-shaped tilesets. Producer/renderer round-trip lossless
15221538
by construction.
1523-
- **5-12 hop range = `r* = ⌈log₄(C/τ)⌉`** evaluated against
1524-
clinical (FMA registration), pixel (Cesium SSE), and tile (OSM
1525-
pyramid) tolerances. Same formula across the three domains; the
1539+
- **5-12 hop range = `r* = ⌈log₄(C/τ)⌉`** (the `b = 16` reduction of
1540+
`r* = ⌈2·log_b(C/τ)⌉`) evaluated against clinical (FMA
1541+
registration), pixel (Cesium SSE), and tile (OSM pyramid)
1542+
tolerances. Same formula across the three domains; the
15261543
per-domain Jirak certificate supplies `C`.
15271544
- **theta ∈ [1.45, 1.6] window** is the regime where the Jirak
15281545
bound applies cleanly to palette256 distances (ADR-024 codec).

0 commit comments

Comments
 (0)