From 95e2863762f4979dcdd543c8c758ed4a8d5add94 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 16 Sep 2026 18:54:23 +0000 Subject: [PATCH 1/4] facet: fold the per-axis LCP (shared6) into one u64 xor+tzcnt MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit shared_prefix_tiles already reads the whole facet as one register (u128 xor + trailing_zeros/16, one vpxor+tzcnt); the per-axis hi_distance/lo_distance thirty lines above it still walked six bytes in a loop. Same fold, per axis: the six tier bytes are formatted by position into a LE u64 ("{0}…{5}" -f chain, tier 0 lowest), xor, trailing_zeros/8, clamp 6 on xor == 0. Falsifier compares the fold against the loop it replaced at every divergence tier on both axes plus the identical case; disable-verified red by reversing the fold's byte order (fails at "hi t=0"). Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01DCfrD5y19cvFc4AoyydXYv --- crates/lance-graph-contract/src/facet.rs | 59 ++++++++++++++++++++++-- 1 file changed, 55 insertions(+), 4 deletions(-) diff --git a/crates/lance-graph-contract/src/facet.rs b/crates/lance-graph-contract/src/facet.rs index 306208f2d..e9062cf77 100644 --- a/crates/lance-graph-contract/src/facet.rs +++ b/crates/lance-graph-contract/src/facet.rs @@ -223,12 +223,26 @@ impl FacetCascade { } /// Shared coarse→fine prefix length (0..=6) of two 6-byte chains. + /// + /// Folded, not looped: the six bytes are formatted into one `u64` by position + /// (`"{0}{1}{2}{3}{4}{5}" -f chain`, LE so tier 0 is the low byte), and the + /// prefix is `xor` + `trailing_zeros / 8` — the same single-register readout + /// [`shared_prefix_tiles`](Self::shared_prefix_tiles) already uses for the + /// whole facet, applied per axis. The two zero pad bytes at 48..64 are + /// identical on both sides, so `xor == 0` ⇔ all six bytes agree, and the + /// clamp to 6 only ever fires on that case. const fn shared6(a: [u8; 6], b: [u8; 6]) -> u8 { - let mut n = 0u8; - while (n as usize) < 6 && a[n as usize] == b[n as usize] { - n += 1; + let x = Self::fold6(a) ^ Self::fold6(b); + if x == 0 { + 6 + } else { + (x.trailing_zeros() / 8) as u8 } - n + } + + /// `"{0}…{5}" -f chain` — six tier bytes into one LE `u64`, tier 0 lowest. + const fn fold6(c: [u8; 6]) -> u64 { + u64::from_le_bytes([c[0], c[1], c[2], c[3], c[4], c[5], 0, 0]) } /// `hi`-chain distance: `6 − shared hi-prefix` — locality along the `hi` hierarchy, @@ -674,6 +688,43 @@ mod tests { assert_eq!(h.row_match_mask(f), 0b1110); } + /// The folded `shared6` against the byte loop it replaced, at every divergence + /// position and on the identical case. A fold that read the chain big-endian + /// (tier 5 lowest) or forgot the identical-clamp would fail one of these rows. + /// Disable-verified 2026-09-16: reversing `fold6`'s byte order fails `hi t=0`. + #[test] + fn folded_axis_prefix_matches_the_loop_at_every_position() { + const fn looped(a: [u8; 6], b: [u8; 6]) -> u8 { + let mut n = 0u8; + while (n as usize) < 6 && a[n as usize] == b[n as usize] { + n += 1; + } + n + } + let f = FacetCascade::from_bytes(&sample()); + let base = sample(); + // identical: both axes fully shared (the xor == 0 clamp). + assert_eq!(f.hi_distance(f), 0); + assert_eq!(f.lo_distance(f), 0); + // flip exactly tier `t`'s hi byte, then its lo byte: prefix must be `t` on + // that axis and 6 on the other, and equal the loop's answer. + for t in 0..6usize { + for (axis_off, is_hi) in [(1usize, true), (0usize, false)] { + let mut b = base; + b[4 + 2 * t + axis_off] ^= 0x80; + let g = FacetCascade::from_bytes(&b); + let (sh, sl) = (6 - f.hi_distance(g) as usize, 6 - f.lo_distance(g) as usize); + assert_eq!(sh, looped(f.hi_chain(), g.hi_chain()) as usize, "hi t={t}"); + assert_eq!(sl, looped(f.lo_chain(), g.lo_chain()) as usize, "lo t={t}"); + if is_hi { + assert_eq!((sh, sl), (t, 6), "hi flip at tier {t}"); + } else { + assert_eq!((sh, sl), (6, t), "lo flip at tier {t}"); + } + } + } + } + #[test] fn cascade_shapes_are_total_and_class_conditioned() { // Every shape covers all 12 units; index/group_of/level_of are inverses. From ce6664e97125db4eb382fe17093ed6e58c6308a6 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 16 Sep 2026 18:54:53 +0000 Subject: [PATCH 2/4] board: E-FORMAT-SLOT-FOLD-IS-THE-SAME-OP-AS-THE-VL-DESCENT-1 Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01DCfrD5y19cvFc4AoyydXYv --- .claude/board/EPIPHANIES.md | 55 +++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/.claude/board/EPIPHANIES.md b/.claude/board/EPIPHANIES.md index 5990fde3d..80f0e61dc 100644 --- a/.claude/board/EPIPHANIES.md +++ b/.claude/board/EPIPHANIES.md @@ -1,3 +1,58 @@ +## 2026-09-16 (16) — E-FORMAT-SLOT-FOLD-IS-THE-SAME-OP-AS-THE-VL-DESCENT-1 — `"{0}{1}" -f hi,lo`: the register is a template with fixed arity, and both the facet LCP and the ternlogq tail are "pick the template whose arity matches the arguments, never pad them" + +**Status:** MEASURED on the ndarray side (the descent probe, ndarray +`examples/ternlogq_tail_descent_probe.rs`, AVX-512 v4, 3 runs) + SHIPPED on +the contract side (`facet.rs` `shared6` fold, this PR). +**Confidence:** HIGH on both numbers; the analogy is the operator's +(*"Powershell `{0}{1} -F $1,$2` logic"*, 2026-09-16) and is recorded as the +naming, not derived. + +### The one shape + +PowerShell's `-f` fills positional slots of a fixed-arity template; a missing +argument throws — it never zero-pads. Read against this tree: + +| `-f` | contract `facet.rs` | ndarray | +|---|---|---| +| `"{0}{1}" -f hi,lo` | `FacetTier::as_u16` | — | +| `"{0}…{7}" -f class,t0..t5` | `as_u128` (8 u16 tiles, one register) | the xmm rung | +| prefix of two formatted strings | `shared_prefix_tiles` = `u128` xor + `tzcnt/16` | — | +| template arity chosen **by argument count** | — | zmm→ymm→xmm descent for a 1..7-word tail | +| `pack_under` (`64 % L == 0`) | — | already IS `-f` with arity `L` — gated side only | + +### What was un-folded thirty lines from the fold + +`shared_prefix_tiles` read the whole facet as one register; `hi_distance` / +`lo_distance` (`shared6`) still walked six bytes in a loop. Same fold per axis: +`"{0}…{5}" -f chain` → LE `u64`, xor, `trailing_zeros/8`, clamp 6. Falsifier +compares fold vs the loop at every divergence tier on both axes; disable-run +(reversed byte order) fails at `hi t=0`. + +### What the same shape is worth one repo down (measured, not yet wired) + +`mask_ternlog` pads its 1..7-word tail into three zeroed `[u64; 8]` arrays. +Descending instead (`4 + 2 + 1`, every lane live, all in vector registers): +greedy widest-first wins at every `t >= 2` — **5–8× over padding**, 1.3–1.6× +over all-xmm; `t=6` `4+2` 2.26–2.74 ns vs `2+2+2` 3.29–3.68 vs padded +17.0–18.3. `ogar-r2il`'s `CallMask = [u64; 3]` has zero full chunks, so the +whole op is that tail: 18.1 → 2.3 ns. asm: 33 zmm + 3 ymm + 6 xmm `vpternlogq`, +zero GPR logic on lane data — a descent is not the scalar peel +`codegen-witness.sh` caps at `SLICE_GPR_CAP=6`. + +### Gaps this names (ndarray, not this PR) + +- `U64x4::ternlog` / `U64x2::ternlog` do not exist on the facade; the descent + calls the intrinsics a wrapper would hold. Adding them + rewiring + `mask_ternlog`'s tail is the follow-up. +- No `u16` compare family (`eq_u16_to_mask`) — the `(u8:u8)` rail IS a u16 + tile, and lgj-abi's `simd_rowstore_facet_match` compares classids only. +- An un-gated `pack` sibling of `pack_under` would retire the 12 + hand-rolled `if !tail.is_empty()` sites. + +Cross-ref: ndarray `.claude/knowledge/masking-ops-state.md` (G1/G2 RUN, #310); +`E-THE-SPINE-IS-WHATEVER-THE-READER-ALREADY-HAS-AN-ADDRESS-FOR-1` above — the +`-f` naming is the same muscle-memory argument applied to a register layout. + ## 2026-09-16 (15) — E-THE-SPINE-IS-WHATEVER-THE-READER-ALREADY-HAS-AN-ADDRESS-FOR-1 — the operator's quack redirect, and the four errors of one session that all substituted an address for the thing **Status:** OPERATOR-RULED (the redirect, verbatim below) + MEASURED (the census From 76bb237945319909f42da2a43f441fbd8237ab04 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 16 Sep 2026 19:23:04 +0000 Subject: [PATCH 3/4] =?UTF-8?q?facet:=20axis=20LCP=20reads=20the=20single?= =?UTF-8?q?=20register=20directly=20=E2=80=94=20the=20fold=20was=20already?= =?UTF-8?q?=20done=20at=20mint?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The u128 facet stores every tier as hi:lo by position, so the per-axis prefix is the whole-facet xor masked to that axis's tier bytes, then trailing_zeros/16 past the classid — no hi_chain/lo_chain gather, no per-call re-fold. Replaces fold6 from the previous commit. Same tests; disable-verified red by swapping HI_BYTES/LO_BYTES. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01DCfrD5y19cvFc4AoyydXYv --- crates/lance-graph-contract/src/facet.rs | 56 ++++++++++++++---------- 1 file changed, 34 insertions(+), 22 deletions(-) diff --git a/crates/lance-graph-contract/src/facet.rs b/crates/lance-graph-contract/src/facet.rs index e9062cf77..5d06949c4 100644 --- a/crates/lance-graph-contract/src/facet.rs +++ b/crates/lance-graph-contract/src/facet.rs @@ -222,35 +222,46 @@ impl FacetCascade { [t[0].lo, t[1].lo, t[2].lo, t[3].lo, t[4].lo, t[5].lo] } - /// Shared coarse→fine prefix length (0..=6) of two 6-byte chains. + /// Byte mask selecting the `hi` byte of every tier in the LE `u128` facet + /// (bytes 5, 7, … 15; the classid occupies 0..4, tier `t` sits at `4 + 2t`). + const HI_BYTES: u128 = Self::tier_byte_mask(1); + /// Byte mask selecting the `lo` byte of every tier (bytes 4, 6, … 14). + const LO_BYTES: u128 = Self::tier_byte_mask(0); + + const fn tier_byte_mask(axis_off: u32) -> u128 { + let mut m = 0u128; + let mut t = 0; + while t < 6 { + m |= 0xFF << (8 * (4 + 2 * t + axis_off)); + t += 1; + } + m + } + + /// Shared coarse→fine prefix length (0..=6) along one axis, read straight + /// off the single-register facet — no chain gather, no re-fold. /// - /// Folded, not looped: the six bytes are formatted into one `u64` by position - /// (`"{0}{1}{2}{3}{4}{5}" -f chain`, LE so tier 0 is the low byte), and the - /// prefix is `xor` + `trailing_zeros / 8` — the same single-register readout - /// [`shared_prefix_tiles`](Self::shared_prefix_tiles) already uses for the - /// whole facet, applied per axis. The two zero pad bytes at 48..64 are - /// identical on both sides, so `xor == 0` ⇔ all six bytes agree, and the - /// clamp to 6 only ever fires on that case. - const fn shared6(a: [u8; 6], b: [u8; 6]) -> u8 { - let x = Self::fold6(a) ^ Self::fold6(b); + /// The facet's `u128` already holds both axes formatted by position + /// (`"{0}{1}" -f hi,lo` per tier, tier 0 lowest), so the `-f` was done once, + /// at mint. An axis prefix is the whole-facet xor masked to that axis's + /// bytes, then `trailing_zeros / 16` past the 4 classid bytes — the same + /// readout [`shared_prefix_tiles`](Self::shared_prefix_tiles) uses for the + /// whole facet. `xor == 0` under the mask ⇔ all six bytes agree. + const fn shared_axis(x: u128, axis: u128) -> u8 { + let x = x & axis; if x == 0 { 6 } else { - (x.trailing_zeros() / 8) as u8 + ((x.trailing_zeros() - 32) / 16) as u8 } } - /// `"{0}…{5}" -f chain` — six tier bytes into one LE `u64`, tier 0 lowest. - const fn fold6(c: [u8; 6]) -> u64 { - u64::from_le_bytes([c[0], c[1], c[2], c[3], c[4], c[5], 0, 0]) - } - /// `hi`-chain distance: `6 − shared hi-prefix` — locality along the `hi` hierarchy, /// orthogonal to [`lo_distance`](Self::lo_distance). #[inline] #[must_use] pub const fn hi_distance(self, other: Self) -> u8 { - 6 - Self::shared6(self.hi_chain(), other.hi_chain()) + 6 - Self::shared_axis(self.as_u128() ^ other.as_u128(), Self::HI_BYTES) } /// `lo`-chain distance: `6 − shared lo-prefix` — locality along the orthogonal `lo` @@ -258,7 +269,7 @@ impl FacetCascade { #[inline] #[must_use] pub const fn lo_distance(self, other: Self) -> u8 { - 6 - Self::shared6(self.lo_chain(), other.lo_chain()) + 6 - Self::shared_axis(self.as_u128() ^ other.as_u128(), Self::LO_BYTES) } /// Number of fully-matching low **tiles** (0..=8, classid tiles 0–1 first, then the @@ -688,10 +699,11 @@ mod tests { assert_eq!(h.row_match_mask(f), 0b1110); } - /// The folded `shared6` against the byte loop it replaced, at every divergence - /// position and on the identical case. A fold that read the chain big-endian - /// (tier 5 lowest) or forgot the identical-clamp would fail one of these rows. - /// Disable-verified 2026-09-16: reversing `fold6`'s byte order fails `hi t=0`. + /// The masked single-register axis readout against the byte loop it replaced, + /// at every divergence position and on the identical case. A mask off by one + /// byte (hi/lo swapped, or the classid bytes included) or a missing + /// identical-clamp fails one of these rows. Disable-verified 2026-09-16: + /// swapping `HI_BYTES`/`LO_BYTES` fails `hi flip at tier 0`. #[test] fn folded_axis_prefix_matches_the_loop_at_every_position() { const fn looped(a: [u8; 6], b: [u8; 6]) -> u8 { From 45c51996b2b8c2d9343d5e95ac70e8de4c0d0fa3 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 16 Sep 2026 19:23:38 +0000 Subject: [PATCH 4/4] =?UTF-8?q?board:=20E-FORMAT-SLOT-FOLD=20entry=20?= =?UTF-8?q?=E2=80=94=20fold=20once=20at=20mint,=20masked=20axis=20readout?= =?UTF-8?q?=20numbers?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01DCfrD5y19cvFc4AoyydXYv --- .claude/board/EPIPHANIES.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/.claude/board/EPIPHANIES.md b/.claude/board/EPIPHANIES.md index 80f0e61dc..73416feca 100644 --- a/.claude/board/EPIPHANIES.md +++ b/.claude/board/EPIPHANIES.md @@ -23,10 +23,17 @@ argument throws — it never zero-pads. Read against this tree: ### What was un-folded thirty lines from the fold `shared_prefix_tiles` read the whole facet as one register; `hi_distance` / -`lo_distance` (`shared6`) still walked six bytes in a loop. Same fold per axis: -`"{0}…{5}" -f chain` → LE `u64`, xor, `trailing_zeros/8`, clamp 6. Falsifier -compares fold vs the loop at every divergence tier on both axes; disable-run -(reversed byte order) fails at `hi t=0`. +`lo_distance` (`shared6`) still gathered six strided bytes per axis into a +chain and walked them. First cut re-folded the gathered chain into a `u64` +(1.5× — the gather dominated). The operator's correction (*"fold the +PowerShell logic ONCE"*): the `u128` facet already holds both axes by +position, so an axis prefix is the whole-facet xor **masked to that axis's +tier bytes** (`HI_BYTES` = bytes 5,7,…,15; `LO_BYTES` = 4,6,…,14), then +`trailing_zeros/16` past the classid — the `-f` was done at mint, never per +call. Measured, 64K random pairs: loop 12.5 ns → masked readout **5.8 ns** for +both axes (2.9 ns each, the same as the whole-facet `prefix_distance`). +Falsifier compares against the loop at every divergence tier on both axes; +disable-run (swap `HI_BYTES`/`LO_BYTES`) fails at `hi flip at tier 0`. ### What the same shape is worth one repo down (measured, not yet wired)