docs(adr): add ADR-024 — Palette256 + HHTL codec as universal compression primitive#39
Merged
Merged
Conversation
…sion primitive
Names an existing primitive (three independent deployments + one
empirical anchor) rather than proposing one. Companion to ADR-022
(The Firewall) and ADR-023 (IR-as-wire-truth).
# The codec
HHTL prefix (NiblePath / quadkey / class identity)
↓ establishes spatial / semantic frame
within-frame values cluster
↓ quantize to 256-index palette
↓ const-table lookup (compile-time HHTL where possible)
1-byte index per element, sub-µs decode, zero heap allocation
# Three already-deployed instances (verified, not narrative)
- Security mesh — Binary16K = [u64; 256] in
MedCare-rs/crates/medcare-analytics/src/graph_contract.rs:36;
Hamming-popcount on _effectiveReaders at the inner / hot
path; wired into production at column_mask_bridge.rs →
medcare-server/state.rs:167, 265, 439.
- Attention — bgz-tensor WeightPalette::build(…, 256) +
AttentionTable::build (crates/bgz-tensor/examples/
compare_stacked_vs_i16.rs:90-92).
- Distance — lance-graph-arm-discovery aerial codebook,
measured ρ = 0.9973 vs cosine — the empirical anchor.
The runtime side's BindSpace dissolution work (bardioc PR #18 /
lance-graph PR #470) hinted at the same compression strategy via the
Quintenzirkel qualia codebook (8 B → 1-2 B per row).
# Adoption checklist for new domains
1. Identify the prefix (NiblePath / quadkey / class identity).
2. Identify the palette domain — which values cluster?
3. Build the palette + measure ρ-vs-reference. Target ≥ 0.99 to
match the arm-discovery anchor.
4. Decode = const-table lookup (zero-allocation hot path).
# The 256-ceiling escape hatches (in the ADR body, not in callouts)
Per runtime-session's "name the escape hatch upfront" tightening so
reviewers don't spend the first session asking about long-tail:
- Per-tile / per-frame palettes — cheapest; different frame,
different 256 entries.
- Hierarchical palettes — coarser at higher quadkey levels, finer
per leaf. Mirrors the tile pyramid + SH L0/L1 vs L2/L3 split in
splat-fit.
- Palette-64K upgrade — 2 bytes/index, for measured cases only
(not speculation).
# Two next-domain adopters queued
- D-OSM-2 (OSM tag palette + tile-local coordinate quantization)
— per lance-graph PR #473 (cesium-osm-substrate-v1.md). Reports
ρ-vs-reference on first per-country PBF run per the runtime
session's §11 follow-up commitment.
- D-SPLAT-4 (SH-aware palette extension on the Gaussian3D
carrier).
# The falsifiable property
"The same compile-time HHTL prefix + palette256 codec decodes
(a) _effectiveReaders for row auth, (b) OSM way attributes at
zoom-21 tile, and (c) FMA-bone SH coefficients at sub-microsecond
per element with zero heap allocation."
If that property holds across all three, the substrate is doing
its job. If it fails on one, the substrate is leaking dialect into
the codec.
# Cross-references named in the ADR
Three FINDING-grade anchors (per runtime-session's "name existing
primitive rather than propose one" tightening):
- lance-graph/.claude/board/EPIPHANIES.md:28
- lance-graph/.claude/knowledge/old-stack-capability-parity.md §3.39
- lance-graph-arm-discovery (ρ = 0.9973 vs cosine)
Plus the file:line citations for all three production deployments
+ cross-references to ADR-022 / ADR-023 / THE-FIREWALL.md /
HEALTHCARE-TRANSCODING.md / RDF-OWL-ALIGNMENT.md.
PII abort-guard (word-boundary): CLEAN.
https://claude.ai/code/session_01PBTGaPCSnnt6u3pjXpbLwY
This was referenced Jun 5, 2026
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
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
New ADR-024 in
docs/ARCHITECTURAL-DECISIONS-2026-06-04.md(+180 LOC). Names an existing primitive — three independent palette256 deployments + one empirical anchor (ρ = 0.9973 vs cosine inlance-graph-arm-discovery) — rather than proposing one. Companion to ADR-022 (The Firewall) and ADR-023 (IR-as-wire-truth).Per the runtime session's three explicit tightenings:
The codec
Three already-deployed instances (verified by the runtime session)
Binary16K = [u64; 256]@MedCare-rs/.../graph_contract.rs:36+ Hamming popcount on_effectiveReaders; production wire-up atcolumn_mask_bridge.rs→medcare-server/state.rs:167, 265, 439bgz-tensor::WeightPalette::build(…, 256)+AttentionTable::build@crates/bgz-tensor/examples/compare_stacked_vs_i16.rs:90-92lance-graph-arm-discoveryaerial codebook — ρ = 0.9973 vs cosine (measured, FINDING-grade)Runtime side's BindSpace dissolution work (bardioc #18 / lance-graph #470) hinted via the Quintenzirkel qualia codebook (8 B → 1-2 B per row).
Adoption checklist for new domains
ρ-vs-reference becomes the adoption contract — reported once per domain at adoption time. Keeps the empirical floor honest as the primitive spreads.
256-ceiling escape hatches (in the ADR body)
splat-fit)Two next-domain adopters queued
cesium-osm-substrate-v1.md); ρ-vs-reference reported on first per-country PBF run per runtime-session's §11 commitmentGaussian3DcarrierThe falsifiable property
"The same compile-time HHTL prefix + palette256 codec decodes (a)
_effectiveReadersfor row auth, (b) OSM way attributes at zoom-21 tile, and (c) FMA-bone SH coefficients at sub-microsecond per element with zero heap allocation."If that property holds across all three, the substrate is doing its job. If it fails on one, the substrate is leaking dialect into the codec.
Cross-arc reuse — sharpens the substrate-reuse claim
The
docs/RDF-OWL-ALIGNMENT.md §10"geographic litmus complements anatomical" framing cashes out as: FMA-bones and OSM-vectors use the same codec (palette256 + HHTL prefix), not just the same IR. TheDOMAIN-INSTANCES.md §2.6callout queued for the post-lance-graph-#473 docs PR will reference ADR-024 as the falsifiable property.Verification
cargo check --workspace --all-targets→ clean (docs-only PR)Runtime-side commitment
Once this merges, the runtime session will file a small §11 callout to lance-graph PR #473 (
cesium-osm-substrate-v1.md) tying D-OSM-2 + D-SPLAT-4 to this ADR with the ρ-vs-reference measurement as the falsifiability test. That closes the loop from the runtime side — the falsifiable property is testable at D-OSM-2 implementation time, not deferred.https://claude.ai/code/session_01PBTGaPCSnnt6u3pjXpbLwY