Merge pull request #270 from AdaWorldAPI/claude/remove-typos-ci

ci: remove typos spell-check job (too many false positives)

Author: AdaWorldAPI

.claude/board/EPIPHANIES.md

@@ -1124,3 +1124,65 @@ Estimated 100× speedup for encoding (O(1) table lookup vs O(256) L1 per query).
 - **TD-DIST-3** (Palette distance table): `Palette::build_distance_table()` →
   `PaletteDistanceTable` with O(1) `distance(a, b)` and `edge_distance(a, b)`.
   128 KB table, L2-resident. Status: **PAID**.
+
+## 2026-04-26 — TD-PALETTE-SENTINEL: 257th sentinel slot in palette distance/compose tables
+
+**Status:** Open (low priority — historical aspirational design, no current need)
+
+The 2026-04-20 resolution-hierarchy epiphany described the bgz17 HIP layer
+as `256×257` (256 archetypes + 1 sentinel). Implementation shipped `k×k`
+without the sentinel. See EPIPHANIES.md 2026-04-26 CORRECTION for full
+context.
+
+**Why deferred:**
+- Adding a 257th index requires widening palette indices from `u8` to `u16`
+- `PaletteEdge` wire format doubles from 3 bytes to 6 bytes per edge
+- `MAX_PALETTE_SIZE = 256` is a deliberate u8-ceiling design choice
+- The three sentinel roles (unknown/null/identity) are already covered by
+  existing mechanisms: `Palette::nearest()` clamps unknowns, `identity()`
+  returns the closest-to-zero archetype.
+
+**Revisit when:** a real "absent edge" code path materializes (e.g., a
+sparse mxm that needs to distinguish "no relation" from "relation = 0
+distance"), or when the palette grows beyond 256 entries (which would
+also force u16 indices).
+
+## 2026-04-26 — TD-AWARENESS-INLINE-1: awareness should be BF16-mantissa-inline, not driver-global
+
+**Status:** Open (P-0 architectural, scope: substrate-wide)
+
+Per EPIPHANIES.md 2026-04-26 "awareness should be BF16-mantissa-inline":
+the current `ShaderDriver.awareness: RwLock<Vec<GrammarStyleAwareness>>`
+is driver-global and separate from the stream. This wastes the CPU's
+20-200 ns random-access advantage and recreates the parser/processor
+split that AGI is supposed to dissolve.
+
+**The correct shape:** every stream operation returns `(value, awareness)`,
+where awareness (7-8 bits, BF16-mantissa-equivalent) is derived inline
+from operation properties (bit-purity, distribution shape, residual norm,
+match strength). Awareness composes through the cascade the same way
+values compose.
+
+**Wedge for the smallest viable adoption:**
+1. Extend `contract::distance::Distance` with
+   `distance_with_awareness(&self, other) -> (u32, u8)`. 8 bits per
+   measurement; 11% overhead vs raw distance.
+2. Add `Aware` trait and `Annotated<T>` to contract.
+3. Implement awareness derivation for the four primary operations:
+   `vsa_bind`, `vsa_bundle`, `hamming`, `cosine`.
+4. Update `ShaderDriver::dispatch` to compose inline awareness over
+   the cascade. The driver-global `GrammarStyleAwareness` becomes a
+   bootstrap seed, not the per-cycle source of truth.
+
+**Size budget:** 11-12% overhead on stream payloads (vs 43.75% for
+BF16 mantissa as a fraction of value), because the value plane is
+much wider here than in floating-point.
+
+**Why deferred:** scope is substrate-wide. Touches the contract
+Distance trait (just shipped TD-DIST-1), every SIMD operation in
+ndarray::hpc, the shader driver's cascade, and the BindSpace SoA.
+Should be designed as one coherent commit, not piecemeal.
+
+**Revisit when:** the next architectural sweep covers the awareness
+dimension. Until then, awareness stays driver-global. The epiphany
+documents the correct direction so future work doesn't re-derive it.

.claude/board/TECH_DEBT.md

@@ -19,29 +19,80 @@ env:
   RUSTFLAGS: "-C debuginfo=1 -C target-cpu=x86-64-v3"
 
 jobs:
+  # Clippy runs FIRST and is mandatory — logical soundness before syntax.
+  # Discipline:
+  #   - NEVER use `clippy --fix` for unused-import warnings; they signal
+  #     missing wiring, not dead code. Fix the wiring or add `#[allow]`
+  #     with a comment explaining why.
+  #   - Each clippy violation is owned by the author of the code that
+  #     introduced it; resolve manually.
+  #   - Run clippy in batches (per-feature combo), not after every file edit.
+  clippy:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 25
+    defaults:
+      run:
+        working-directory: lance-graph
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          path: lance-graph
+      - name: Checkout AdaWorldAPI/ndarray (sibling dependency)
+        uses: actions/checkout@v4
+        with:
+          repository: AdaWorldAPI/ndarray
+          path: ndarray
+      - name: Setup rust toolchain
+        run: |
+          rustup toolchain install stable
+          rustup default stable
+          rustup component add clippy
+      - uses: Swatinem/rust-cache@v2
+        with:
+          shared-key: "lance-graph-deps"
+          workspaces: lance-graph/crates/lance-graph
+      - name: Install dependencies
+        run: |
+          sudo apt update
+          sudo apt install -y protobuf-compiler
+      # Clippy is gated tier-by-tier as the codebase incrementally adopts it.
+      # PRs that touch a new crate own that crate's clippy debt before merging.
+      #
+      # Tier A (mandatory, gating): zero-dep contract crate
+      - name: Clippy contract (zero-dep, mandatory)
+        run: cargo clippy --manifest-path crates/lance-graph-contract/Cargo.toml --lib --tests -- -D warnings
+      # Tier B (advisory until incrementally cleaned, non-gating):
+      #   lance-graph core has ~91 pre-existing clippy violations to be paid down
+      #   in subsequent PRs (TD-CLIPPY-LG-1). Don't auto-fix — each violation
+      #   is a wiring/refactor decision owned by the introducing author.
+      - name: Clippy lance-graph (advisory)
+        continue-on-error: true
+        run: cargo clippy --manifest-path crates/lance-graph/Cargo.toml --lib --tests -- -D warnings
+
   format:
     runs-on: ubuntu-24.04
     timeout-minutes: 15
+    needs: clippy
+    defaults:
+      run:
+        working-directory: lance-graph
     steps:
       - uses: actions/checkout@v4
+        with:
+          path: lance-graph
+      - name: Checkout AdaWorldAPI/ndarray (sibling dependency for cargo metadata)
+        uses: actions/checkout@v4
+        with:
+          repository: AdaWorldAPI/ndarray
+          path: ndarray
       - uses: actions-rust-lang/setup-rust-toolchain@v1
         with:
           components: rustfmt
       - name: Check formatting
         run: cargo fmt --manifest-path crates/lance-graph/Cargo.toml -- --check
 
-  # clippy: runs LOCALLY as our internal pre-check, not on GitHub CI.
-  # GitHub CI focuses on compile + test + format + typos.
-  # Clippy discipline documented in CODING_PRACTICES.md:
-  #
-  #   cargo clippy --features lab -- -D warnings
-  #   cargo clippy --features serve -- -D warnings
+  # typos / spell-check removed 2026-04-26: too many false positives on
+  # technical jargon (NARS terms, codec acronyms, German loanwords used in
+  # the cognitive stack). Spelling discipline is a code-review concern,
+  # not a CI gate.
 
-  typos:
-    name: Spell Check
-    runs-on: ubuntu-24.04
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-      - name: Check spelling
-        uses: crate-ci/typos@v1.26.0

.github/workflows/style.yml

@@ -9,6 +9,8 @@
 //! After quantization, GPTQ-style Hessian compensation adjusts remaining
 //! weights to minimize output error (not weight error).
 
+// Cluster used by future per-cluster anomaly reporting
+#[allow(unused_imports)]
 use ndarray::hpc::clam::{ClamTree, Cluster};
 use ndarray::hpc::fft::wht_f32;
 use ndarray::hpc::quantized::{
@@ -18,6 +20,8 @@ use ndarray::hpc::quantized::{
     QuantParams,
 };
 use ndarray::hpc::cam_pq::kmeans;
+// cosine_f32_to_f64_simd used by tests and future GPTQ compensation
+#[allow(unused_imports)]
 use ndarray::hpc::heel_f64x8::cosine_f32_to_f64_simd;
 use crate::stacked_n::{bf16_to_f32, f32_to_bf16};
 
@@ -75,7 +79,7 @@ fn hadamard_rotate(v: &[f32], dim: usize) -> Vec<f32> {
 fn rows_to_fingerprint_bytes(rows: &[Vec<f32>]) -> (Vec<u8>, usize) {
     if rows.is_empty() { return (vec![], 0); }
     let dim = rows[0].len();
-    let fp_bytes = (dim + 7) / 8;
+    let fp_bytes = dim.div_ceil(8);
     let mut flat = vec![0u8; rows.len() * fp_bytes];
     for (ri, row) in rows.iter().enumerate() {
         for (i, &v) in row.iter().enumerate() {
@@ -107,8 +111,8 @@ fn classify_rows_by_lfd(tree: &ClamTree) -> Vec<RowPrecision> {
     //   Bottom 70% → i4+i2 (regular, well-clustered)
     let mut sorted_lfd: Vec<f64> = row_lfd.clone();
     sorted_lfd.sort_by(|a, b| a.partial_cmp(b).unwrap());
-    let p70 = sorted_lfd[n * 70 / 100.max(1)];
-    let p90 = sorted_lfd[n * 90 / 100.max(1)];
+    let p70 = sorted_lfd[n * 70 / 100];
+    let p90 = sorted_lfd[n * 90 / 100];
 
     row_lfd.iter().map(|&lfd| {
         if lfd > p90 { RowPrecision::Passthrough }
@@ -123,7 +127,7 @@ impl AdaptiveCodecTensor {
         rows: &[Vec<f32>],
         k: usize,
         is_kv_proj: bool,
-        calibration_inputs: Option<&[Vec<f32>]>,
+        _calibration_inputs: Option<&[Vec<f32>]>,
     ) -> Self {
         let n = rows.len();
         let n_cols = if n > 0 { rows[0].len() } else { 0 };

crates/bgz-tensor/src/adaptive_codec.rs

@@ -126,9 +126,9 @@ impl AttentionTable {
         let n_k = k_indices.len();
         let mut scores = vec![0u16; n_q * n_k];
 
-        for i in 0..n_q {
-            for j in 0..n_k {
-                scores[i * n_k + j] = self.distance(q_indices[i], k_indices[j]);
+        for (i, &qi) in q_indices.iter().enumerate().take(n_q) {
+            for (j, &kj) in k_indices.iter().enumerate().take(n_k) {
+                scores[i * n_k + j] = self.distance(qi, kj);
             }
         }
 
@@ -152,9 +152,9 @@ impl AttentionTable {
         let n_k = k_indices.len();
         let mut sparse = Vec::new();
 
-        for i in 0..n_q {
-            for j in 0..n_k {
-                let d = self.distance(q_indices[i], k_indices[j]);
+        for (i, &qi) in q_indices.iter().enumerate().take(n_q) {
+            for (j, &kj) in k_indices.iter().enumerate().take(n_k) {
+                let d = self.distance(qi, kj);
                 if d < threshold {
                     sparse.push((i, j, d));
                 }

crates/bgz-tensor/src/attention.rs

@@ -59,10 +59,10 @@ impl Belichtungsmesser {
         // 12 quarter-sigma bands centered on mean
         // Band edges: μ - 3σ, μ - 2.5σ, μ - 2σ, ..., μ + 2.5σ, μ + 3σ
         let mut edges = [0u32; N_BANDS + 1];
-        for i in 0..=N_BANDS {
+        for (i, edge) in edges.iter_mut().enumerate().take(N_BANDS + 1) {
             let offset = -3.0 + i as f64 * 0.5; // -3σ to +3σ in 0.5σ steps
             let val = (mean + offset * sigma).max(0.0);
-            edges[i] = val as u32;
+            *edge = val as u32;
         }
         // Last edge extends to max
         edges[N_BANDS] = u32::MAX;
@@ -79,8 +79,8 @@ impl Belichtungsmesser {
         }
 
         let mut bands = [Band { lo: 0, hi: 0, density: 0.0 }; N_BANDS];
-        for b in 0..N_BANDS {
-            bands[b] = Band {
+        for (b, band) in bands.iter_mut().enumerate().take(N_BANDS) {
+            *band = Band {
                 lo: edges[b],
                 hi: edges[b + 1],
                 density: counts[b] as f32 / n as f32,
@@ -93,8 +93,8 @@ impl Belichtungsmesser {
     /// Default bands when no calibration data is available.
     fn default_bands() -> Self {
         let mut bands = [Band { lo: 0, hi: 0, density: 0.0 }; N_BANDS];
-        for b in 0..N_BANDS {
-            bands[b] = Band {
+        for (b, band) in bands.iter_mut().enumerate().take(N_BANDS) {
+            *band = Band {
                 lo: b as u32 * 1000,
                 hi: (b as u32 + 1) * 1000,
                 density: 1.0 / N_BANDS as f32,

crates/bgz-tensor/src/belichtungsmesser.rs

@@ -14,6 +14,8 @@
 //! ```
 
 use crate::stacked::StackedBF16x4;
+// BASE_DIM and Base17 reserved for future PCDVQ-weighted distance
+#[allow(unused_imports)]
 use crate::projection::{BASE_DIM, Base17};
 
 /// A 12-bit codebook index: cluster(6) + entry(6) = 4096 entries.

crates/bgz-tensor/src/codebook4096.rs

@@ -12,7 +12,11 @@
 //!   - Highlight compression for large-magnitude roles (Gate)
 //!   - 28 bytes metadata per model for exact decode
 
+// StackedN reserved for future stacked-resolution codebook path
+#[allow(unused_imports)]
 use crate::stacked_n::{StackedN, cosine_f32_slice};
+// gamma_phi_encode/decode reserved for future per-codebook calibration path
+#[allow(unused_imports)]
 use crate::gamma_phi::{GammaProfile, calibrate_gamma, gamma_phi_encode, gamma_phi_decode};
 use std::f64::consts::GOLDEN_RATIO;
 
@@ -191,7 +195,7 @@ fn gamma_phi_cosine_to_u8(
     min_cos: f64,
     max_cos: f64,
     role_gamma: f32,
-    phi_scale: f32,
+    _phi_scale: f32,
 ) -> u8 {
     // Normalize cosine to [0, 1]
     let range = (max_cos - min_cos).max(1e-10);

crates/bgz-tensor/src/codebook_calibrated.rs

@@ -12,6 +12,8 @@
 //! Recovery quality depends on SNR = √(d×SPD / N_members).
 //! At SPD=32, d=17: SNR(N=6) ≈ 9.5 → expected Pearson ~0.96
 
+// cosine_f32_slice reserved for future fold quality measurement
+#[allow(unused_imports)]
 use crate::stacked_n::{StackedN, bf16_to_f32, f32_to_bf16, cosine_f32_slice};
 
 /// Euler-Mascheroni constant γ ≈ 0.5772156649...
@@ -219,7 +221,7 @@ pub fn euler_gamma_fold(members: &[Vec<f32>], spd: usize) -> FoldedFamily {
         .map(|&v| f32_to_bf16(v as f32))
         .collect();
 
-    let mut folded = StackedN {
+    let folded = StackedN {
         samples_per_dim: spd,
         data: folded_bf16,
     };
@@ -307,12 +309,12 @@ pub fn gate_test(members: &[Vec<f32>], spd: usize) -> FoldResult {
     let family = euler_gamma_fold(members, spd);
 
     let mut pearsons = Vec::with_capacity(n);
-    for j in 0..n {
+    for (j, member) in members.iter().enumerate().take(n) {
         let recovered = euler_gamma_unfold(&family, j);
 
         // Compute Pearson between original and recovered
         // (on the hydrated StackedN representation, not raw f32)
-        let orig_enc = StackedN::from_f32(&members[j], spd);
+        let orig_enc = StackedN::from_f32(member, spd);
         let orig_f32 = orig_enc.hydrate_f32();
 
         let r = crate::quality::pearson(

crates/bgz-tensor/src/euler_fold.rs

@@ -16,6 +16,8 @@
 //! Storage: k×k i8 table (64 KB at k=256) + 8 bytes family gamma.
 
 use crate::palette::WeightPalette;
+// Base17 reserved for future Base17-direct Fisher z table path
+#[allow(unused_imports)]
 use crate::projection::Base17;
 
 /// Per-family gamma for Fisher z encoding.