docs(adr): add ADR-025 — Probe-free hot path completes the substrate-doctrine canon#44
Conversation
…doctrine canon
The one-sentence pin:
"Address arithmetic (helix + HHTL) gives geometry; Jirak
certificate (jc) gives error; together they give level — and
the level is the only thing the hot path picks."
Companion to ADR-022 / ADR-023 / ADR-024; closes the substrate-
doctrine canon (boundary / IR / codec / selection — four floors).
# What's named in this ADR (existing, not proposed)
Three independent address-as-geometry surfaces + one bound machinery,
all already deployed:
- Cesium 3D Tiles 1.1 implicit_tiling (closed-form child bounds
from parent + index)
- Helix half-orb placement (centroid + Σ derived from prefix-bit
arithmetic via the golden-stride template)
- HHTL radix-prefix routing (identity-IS-address — ADR-023)
- jc::weyl (1-D star-discrepancy at representative N) +
jc::jirak (rate n^{-(p/2-1)} for p ∈ (2,3], n^{-1/2} in L^q
for p ≥ 4 under weak dependence) — the I-NOISE-FLOOR-JIRAK
iron rule in CLAUDE.md.
# Decision — the substrate doctrine completed
Three composable primitives form the address-and-error substrate;
hot path picks LEVEL only, branch-free:
- helix + HHTL ──▶ geometry (closed-form, branch-free)
- jc::weyl + jc::jirak ──▶ error (predicted per-level,
deployment-static)
- Together ──▶ level (smallest L where predicted_error_L < tol)
Tile bounding_volume becomes a DERIVED field, not stored — both
producer and renderer compute it from the same NiblePath arithmetic;
no float-rounding daylight.
# The falsifiable property (verified by absence)
The hot path takes zero data-dependent branches. Verified by:
- No `if residual < threshold` patterns in crates/cesium/src/
sse.rs after D-CESIUM-IMPLICIT-HELIX lands
- No `try_then_fallback` patterns in registration solvers after
D-JC-PREDICT-LOD lands
- No bounds-check / metadata-fetch round-trip after
D-HELIX-HHTL-BOUNDS lands
# Three queued deliverables (runtime-side; mirror ADR-024 D-OSM-2/D-SPLAT-4)
- D-HELIX-HHTL-BOUNDS — helix::bounds(nibblepath) +
helix::centroid(nibblepath) (50-200 LOC, crates/helix)
- D-CESIUM-IMPLICIT-HELIX — extend crates/cesium/src/implicit_
tiling.rs with the helix backend (small diff)
- D-JC-PREDICT-LOD — jc::predict_lod(scene_cert, tolerance) →
level (crates/jc)
Per the runtime session's preceding analysis, they will file §11
ADR-025 callouts on cesium-osm-substrate-v1.md + splat-native-
ultrasound-v1.md once this ADR lands — same cross-arc symmetry
pattern as ADR-024 (lance-graph PR #475 + PR #476).
# Honest scope (in the ADR body so reviewers don't ask)
Doesn't:
- help when 95% of queries are bad-case (savings collapse)
- help if dependence structure changes at scale (Wikidata-scale
locality is a separate slab)
Requires:
- jc certificate per scene class (deployment-static; one-time
measurement; not per-query)
# Honest discipline note
I (OGAR session) have not personally verified runtime-side artifacts
(crates/jc, crates/helix, crates/cesium/src/{sse,implicit_tiling}.rs,
CLAUDE.md I-NOISE-FLOOR-JIRAK). Citations are taken as authoritative
from the runtime session's 2026-06-05 cross-session analysis — same
verification pattern under which ADR-024's three deployments + ρ =
0.9973 anchor landed. The §11 ADR-025 amendments the runtime session
will file are the receipts that close the loop from their side.
# Verification
cargo check --workspace --all-targets -> clean (docs-only)
PII abort-guard (word-boundary) -> CLEAN
# The four-ADR canon now reads
022 — boundary (no serialization in hot path)
023 — IR (Class is wire truth; dialects absorbed by adapters)
024 — codec (palette256 + HHTL = 1-byte index, sub-µs decode,
ρ ≥ 0.99)
025 — selection (address gives geometry, certificate gives error,
together give level; hot path picks level only,
branch-free)
Each closes a different floor; together they describe a substrate
whose hot path is deterministic by construction.
https://claude.ai/code/session_01PBTGaPCSnnt6u3pjXpbLwY
![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: 96d73a24c4
ℹ️ 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".
| `n` = current sample size at level L (e.g. n ≈ 16^r for a | ||
| 4-ary radix pyramid) | ||
| `predicted_error_L = C · n^{-1/2}` (L^q regime, which the | ||
| Σ-sandwich Mahalanobis distance lives in) | ||
| `r* = ⌈log₄(C/τ)⌉` for clinical tolerance τ — closed-form, |
There was a problem hiding this comment.
This implementation recipe mixes incompatible assumptions: a 4-ary radix pyramid grows as 4^r, while the stated r* = ⌈log₄(C/τ)⌉ only follows from n ≈ 16^r with predicted_error_L = C · n^{-1/2}. If D-JC-PREDICT-LOD is implemented against the documented 4-ary pyramid, it will choose a level that is roughly half as deep as needed and can leave the predicted error above tolerance; either document a 16-way radix here or change the derived level formula.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in PR #45 (rebased on current main). You were right — the doc mixed a 4-ary label with a 16^r-derived formula. The pyramid increases ×4 in both x and y per hop, so n = 16^r (= 4×4); the §2 derivation is now explicit (r* = ⌈2·log_b(C/τ)⌉, specialized to b=16 → ⌈log₄(C/τ)⌉), the 4-ary label is removed, and an implementer note warns that pairing ⌈log₄⌉ with an actual 4-ary pyramid picks half the needed depth. Numerically re-verified.
2 participants
Summary
New ADR-025 in
docs/ARCHITECTURAL-DECISIONS-2026-06-04.md(+242 LOC). Closes the substrate-doctrine canon (022 / 023 / 024 / 025). Names an existing capability surface — three address-as-geometry surfaces + one bound machinery, all already deployed — rather than proposing a new mechanism.The one-sentence pin:
Why now
The runtime session's status update (2026-06-05) confirmed the ADR-024 cross-arc symmetry is sealed (
lance-graphPR #475 + PR #476 — §11 callouts on bothcesium-osm-substrate-v1.mdD-OSM-2 andsplat-native-ultrasound-v1.mdD-SPLAT-4 adopters). They explicitly signaled: "Small §11 amendment if the cesium-osm or splat-native sides want the ADR-025 (helix + HHTL + jc addressing) pin once that ADR lands."ADR-025 is now well-justified: same cross-arc symmetry pattern ADR-024 followed.
What's named in the ADR (existing, not proposed)
Three independent address-as-geometry surfaces:
One bound machinery:
jc::weyl+jc::jirak— theI-NOISE-FLOOR-JIRAKiron rule in CLAUDE.md (raten^{-(p/2-1)}for p ∈ (2,3],n^{-1/2}in L^q for p ≥ 4 under weak dependence)The four-ADR canon now reads
Classis wire truth; dialects absorbed by adaptersEach closes a different floor; together they describe a substrate whose hot path is deterministic by construction.
The falsifiable property — verified by absence
The hot path takes zero data-dependent branches. Verified after the three queued deliverables land:
if residual < thresholdpatterns incrates/cesium/src/sse.rs(D-CESIUM-IMPLICIT-HELIX)try_then_fallbackpatterns in registration solvers (D-JC-PREDICT-LOD)D-HELIX-HHTL-BOUNDS)If
if-branches reappear on data, the substrate is leaking probing into the codec.Three queued deliverables (runtime-side; mirror ADR-024 pattern)
helix::bounds(nibblepath)+helix::centroid(nibblepath)— closed-form (50-200 LOC)crates/heliximplicit_tiling.rswith helix backend (small diff)jc::predict_lod(scene_cert, tolerance) → levelcrates/jcPer the runtime session's commitment, they'll file §11 ADR-025 callouts on
cesium-osm-substrate-v1.md+splat-native-ultrasound-v1.mdonce this ADR merges — same cross-arc symmetry pattern as ADR-024.Honest scope (in ADR body so reviewers don't ask)
Doesn't:
Requires:
Honest discipline note (in ADR body)
I haven't personally verified
crates/jc,crates/helix,crates/cesium/src/{sse,implicit_tiling}.rs, or the CLAUDE.mdI-NOISE-FLOOR-JIRAKrule from the OGAR side. Citations are taken as authoritative from the runtime session's 2026-06-05 cross-session analysis — same verification pattern under which ADR-024's three deployments +ρ = 0.9973anchor landed. The §11 ADR-025 amendments the runtime session will file are the receipts that close the loop from their side.Verification
cargo check --workspace --all-targets→ clean (docs-only PR)https://claude.ai/code/session_01PBTGaPCSnnt6u3pjXpbLwY