Skip to content

docs(adr): add ADR-024 — Palette256 + HHTL codec as universal compression primitive#39

Merged
AdaWorldAPI merged 1 commit into
mainfrom
claude/adr-024-palette256-hhtl-codec
Jun 5, 2026
Merged

docs(adr): add ADR-024 — Palette256 + HHTL codec as universal compression primitive#39
AdaWorldAPI merged 1 commit into
mainfrom
claude/adr-024-palette256-hhtl-codec

Conversation

@AdaWorldAPI

Copy link
Copy Markdown
Owner

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 in lance-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:

  1. Empirical anchor pinned (ρ = 0.9973 vs cosine — the falsifiable stake)
  2. 256-ceiling escape hatches in body (per-tile / hierarchical / palette-64K — pre-empts reviewer question)
  3. Cross-references to FINDING-grade anchors (EPIPHANIES.md:28 + old-stack-capability-parity.md §3.39 — ADR names existing primitive)

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 by the runtime session)

Domain Receipt
Security mesh Binary16K = [u64; 256] @ MedCare-rs/.../graph_contract.rs:36 + Hamming popcount on _effectiveReaders; production wire-up at column_mask_bridge.rsmedcare-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 — ρ = 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

  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).

ρ-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)

  • Per-tile / per-frame palettes — cheapest; matches the quadkey-prefix discipline
  • Hierarchical palettes — coarser at higher levels, finer per leaf (mirrors the tile pyramid + SH L0/L1 vs L2/L3 split in splat-fit)
  • Palette-64K upgrade — 2-byte index; reserve for measured cases (not speculation)

Two next-domain adopters queued

D-id What Source
D-OSM-2 OSM tag palette + tile-local coordinate quantization lance-graph PR #473 (forthcoming cesium-osm-substrate-v1.md); ρ-vs-reference reported on first per-country PBF run per runtime-session's §11 commitment
D-SPLAT-4 SH-aware palette extension on the Gaussian3D carrier splat-native arc

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-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. The DOMAIN-INSTANCES.md §2.6 callout 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)
  • PII abort-guard (word-boundary): CLEAN

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

…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
@AdaWorldAPI AdaWorldAPI merged commit ae08e68 into main Jun 5, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants