Skip to content

Gate record — M6: Tier B families (K7–K10) → v0.4

Date: 2026-07-03 · Milestone: M6 (PRD 18 §M6) · Decision: PASS with one open coverage deferral (§7-D1: REQ-LEDGER-012 ≥2-machine gate — one registered machine exists; no data invented — carried forward from M5).

1. Objective

Complete the kernel catalog on the first three tiers (scalar + AVX2 + NEON) with the Tier B families K7 hash, K8 unpack, K9 arith, K10 arith_guarded; freeze qhash64 with committed golden vectors; decide the evidence-gated K7 NEON technique with measured data.

2. Files created / modified

Created: include/quiver/{hash,unpack,arith}.h; for f ∈ {hash, unpack, arith, arith_guarded}: src/kernels/<f>/{<f>_scalar_impl.h, <f>_scalar.cpp, <f>_avx2.cpp, <f>_neon.cpp} (16 files); tests/golden/qhash64_vectors.txt; tests/unit/test_{hash,unpack, arith}.cpp; tests/property/prop_{hash,unpack,arith}.cpp; tests/differential/diff_isa_{hash, unpack,arith}.cpp; tests/fuzz/fuzz_{hash,unpack,arith}.cpp + corpus/{hash,unpack,arith}/; bench/micro/bench_{hash,unpack,arith,arith_guarded}.cpp; docs/api/{hash,unpack,arith}.md; docs/investigations/k7-neon-hash.md; docs/releases/v0.4.0.md; this record.

Modified: include/quiver/detail/extern_decls.h + src/dispatch/dispatch_tables.cpp (Tier B symbol inventory + rows); bench/baselines/baseline_avx2.{h,cpp} (Tier B autovec entry points); include/quiver/quiver.h (Tier B surface); bench/CMakeLists.txt + tests/CMakeLists.txt (Tier B targets); tests/fuzz/fuzz_common.h (Decoder::remaining() for the raw-byte unpack harness); .github/workflows/nightly.yml (nine-family fuzz + avalanche active); .github/repo-manifest.json (M6 state); CHANGELOG.md; docs/mkdocs.yml (nav).

3. Requirements satisfied

  • REQ-K7-001..004 — frozen ADR-012 algorithm/constants; cross-ISA/platform bit-identity (256 committed golden vectors + 5 combine rows, reproduced on x86/ARM/macOS; differential suite byte-exact); avalanche/bias gate (distinct-pair-aware band, nightly ≥100k/type); no validity parameter (null-composition idiom on the family page).
  • REQ-K8-001..004 — ADR-026 LSB-first layout; exactly ⌈n·w/8⌉ bytes read from untrusted packed (guard-page + raw-byte fuzz, REQ-SEC-004); w=0 all-zeros/base with nullable packed; width-exhaustive 0..8·sizeof(Out) differential.
  • REQ-K9-001..002 — integer wrapping with no signed-overflow UB path (narrow operands computed in a promotion-safe unsigned type); validity overload = values + mask_combine(kAnd).
  • REQ-K10-001..003 — arith_checked wrapped results + exact count + tail-zeroed position bitmap (ADR-014); arith_saturating exact clamps; 64-bit checked/saturating multiply is the documented scalar concession (family page + ledger).
  • REQ-TEST-015/-016 — dual-oracle Tier B suites; the SMHasher-subset avalanche gate with its documented narrow-domain limitation.
  • REQ-SEC-004 — the untrusted-input read bound, page-guard-tested at every width and raw-byte-fuzz-prioritized.
  • REQ-KERNEL-007 (K7 NEON leg) — GPR-vs-vector decided by measurement on apple-m2-mba (GPR wins ~1.3×; kUseVectorHash=false ships); the losing variant stays compiled and differential/golden/fuzz test-covered via -DQUIVER_K7_HASH_VECTOR=1 (investigations/k7-neon-hash.md).

4. ADRs realized

ADR-012 (qhash64 v1 — frozen constants/rounds, golden vectors committed); ADR-014 (overflow reporting: count + optional position bitmap); ADR-026 (bit-packing layout). ADR-003/006/015/016/023/025 exercised by the new backends; ADR-013 not in scope (no Tier B float reductions). No ADRs amended; no new ADRs (adr_count stays 26).

5. Tests / benchmarks / docs added

Four-family unit/property/differential/fuzz suites; K8 width-exhaustive differential; K10 boundary matrices incl. INT_MIN cases; 256 frozen golden vectors; the nightly avalanche gate; DiffArith.NaNResultsCompareAsClass. Four Tier B microbenchmarks with the bit_width and overflow_density axes and full pre-timing output validation. Docs: three family pages, the K7 investigation, the qhash64 algorithm section, nav + manifest.

Native: dev ctest 122/122; native ASan+UBSan 122/122. ARM64 Linux container: ASan+UBSan 122/122; fuzz_{hash,unpack,arith} clean (≈0.7M/0.25M/0.1M execs). x86-64 Linux container: ASan+UBSan 122/122 (exercises the AVX2 Tier B backends and cross-platform golden vectors); fuzz_{hash,unpack,arith} clean (≈0.9M/0.34M/0.31M execs). Golden vectors byte-identical on all three platforms (REQ-K7-002).

Three latent defects were found by the sanitizer/fuzz gates and fixed before this record: (1) narrow-integer promotion signed-overflow UB in wrapping multiply (kernel + oracle) — ARM UBSan; (2) float NaN op NaN payload non-reproducibility across TU/backend — the arith differential fuzzer, resolved by NaN-class comparison (the M4 policy) with a permanent test + corpus seed; (3) an INT_MIN / -1 division in the MSVC-only 64-bit checked-mul fallback — static review, reordered ahead of the short-circuit guard.

6. Ledger run (the v0.4 Tier B data)

Seven publishable run directories on apple-m2-mba, all at commit 883c08552f35, all zero-deviation (clean-tree) manifests, focused on the DRAM-resident n=65536 size (the low-noise operating point on this fanless machine) and covering the mandated bit_width (K8) and overflow_density (K10) axes. The grid was split into sub-runs because the full sweep exceeds the environment's per-invocation time budget; each sub-run is an independent --out directory (the M5 main+supplement pattern), and entry ids are keyed by run-dir name so they never collide:

  • main — hash + arith (hash clean; arith mul/neon clean, add/autovec excluded at CV>5%).
  • -b — arith_guarded (checked_add ×3 densities both tiers; saturating autovec).
  • -c / -d — unpack bit_width sweep (widths 1/4/7/8 and 16/24/32).
  • -e — arith at 2 s→4 s (neon clean; autovec still excluded).
  • -f — arith autovec at 8 s windows (finally under the CV policy).
  • -g — saturating_add both tiers at 6 s (neon clean).

The streaming K9/K10 classes are noise-prone on this platform (no core pinning or governor control): the add/mul autovec baselines needed 8 s windows to clear the 5% CV gate, and several 2 s attempts are in the runs' rejected_noisy.json — recorded honestly, rerunnable per the disputes guide.

Verdicts (REQ-LEDGER-011, neon vs autovec):

family verdict
K7 hash parity 1.00× — the shipped GPR chain equals autovec (compute-bound; the K7 decision's expected outcome)
K8 unpack byte-aligned widths win 12.8×–42.4× (w=8/16/32, SIMD widening loads); non-byte-aligned ~1.07–1.10× (delegated to scalar)
K9 arith LOSS ~0.90× — the autovectorizer wins pure elementwise add/mul (honest T7 verdict)
K10 arith_guarded arith_checked 1.42× (FLAT across overflow density — the ADR-014 branch-free evidence); arith_saturating 1.65× (native vqadd)

Full entry-referenced tables live on the family pages (docs/api/{hash,unpack,arith}.md).

7. Checks: passed / failed / deferred

Passed: dev ctest 122/122; native + ARM + x86 ASan+UBSan 122/122; three-platform differential fuzzing clean; golden-vector cross-platform equality; bench builds + pre-timing validation under both ARM tiers; mkdocs --strict; repo-lint (manifest M6, entry-id check); adversarial multi-agent review of the Tier B surface (2 findings fixed: bench output-validation completeness, golden-vector count).

Deferred: - D1 (open, milestone-level): REQ-LEDGER-012 ≥2-machine coverage — the registry holds ONE machine (Apple M2, secondary platform). Carried forward from M5; no CI runner may substitute (REQ-LEDGER-007) and no number is invented (Charter T2). Reopen on first registered x86 hardware. - D2: PMU cycles_per_value — absent on Apple by design (REQ-LEDGER-008). - CI matrix legs (GitHub-side) — discharged by the PR checks.

Failed: none outstanding.

8. Ambiguities and deviations

  • A1 (amendment realized from M5): the K7 avalanche gate cannot meet ±0.02 for narrow key domains — an 8-bit key has only 2⁷ distinct flip pairs, so the sampling-error floor exceeds 0.02 for any function. The gate uses a distinct-pair-aware band (max(0.02, 6·√(0.25/distinct_pairs))); at ≥100k samples this is exactly the normative 0.02 for every type of ≥16 bits. Recorded on the hash family page. Proposed smallest amendment: REQ-TEST-016 append "(the ±0.02 threshold applies where the key domain admits ≥ that statistical resolution; narrower domains use a distinct-pair-aware band)".
  • D1 (contract clarification, not a weakening): float NaN results of K9 arithmetic are compared as a class (NaN-ness), not bit-exact, across backends and vs the oracle — IEEE does not pin NaN-payload propagation and the charter forbids fast-math, so bit-identity was never a K9 requirement (REQ-K9-001 is "native IEEE-754"). Same policy as K6 sums (gate M4).
  • D2 (scope note): K8 sub-byte and non-byte-aligned SIMD widths delegate to the scalar core; only byte-aligned widths {8,16,32,64} use vector widening loads. The general shift-network unpacker is a recorded follow-up; every path holds the exact read bound.
  • D3 (concession, per REQ-K10-003): 64-bit checked/saturating multiply is scalar on both SIMD backends; the family page and the ledger state it.

9. Scope exclusions

AVX-512 across all families (M7), packaging/amalgamation (M8), representation study (M9), Graviton and ≥5-µarch coverage (M10). No SQL/parser/planner/engine behavior (charter scope).

10. Documentation rationale / debt

Verdict blocks cite committed entry_ids only (lint-enforced). Debt carried from M5: verdicts exist for one µarch — pages say so explicitly; x86 verdict columns appear with hardware. The K8 general sub-byte SIMD unpacker and the K7 shrn-alternative remain recorded follow-ups.

11. Final gate decision

PASS with the §7-D1 ≥2-machine coverage deferral recorded as open. Every buildable, testable, and documentable M6 deliverable exists and is validated on three platforms (native macOS, ARM Linux, x86 Linux) under ASan+UBSan with clean differential fuzzing; the qhash64 golden vectors reproduce byte-identically everywhere; the evidence-gated K7 NEON decision is made from measured data with the losing variant kept test-covered; and the ledger publishes exactly what was measured on registered hardware — wins (K8 byte-aligned, K10) and a loss (K9) alike — and nothing invented. Gate+ actions after merge: tag v0.4.0.