@elizaos/app-core 2.0.0-alpha.85 → 2.0.0-beta.2

package/scripts/aosp/llama-cpp-patches/polarquant/0001-Q4_POLAR-register-GGML_TYPE_Q4_POLAR-45-and-block_q4.patch

@@ -0,0 +1,108 @@
+From 293c00b2ed7948fcfd50cfc83acd9480b446f2ff Mon Sep 17 00:00:00 2001
+From: lalalune <shawmakesmagic@gmail.com>
+Date: Sat, 9 May 2026 02:45:15 -0700
+Subject: [PATCH 1/4] Q4_POLAR: register GGML_TYPE_Q4_POLAR=45 and
+ block_q4_polar layout
+
+Reserve type tag 45 for PolarQuant Q4 (128-element block, fp16 norm +
+4-bit Lloyd-Max codes + optional 1-bit QJL residual). Add the
+block_q4_polar struct (82 bytes) to ggml-common.h next to the existing
+TBQ blocks, and forward-declare the encoder/decoder/quantize entry
+points in ggml-quants.h and ggml-cpu/quants.h.
+---
+ ggml/include/ggml.h        |  3 ++-
+ ggml/src/ggml-common.h     | 14 ++++++++++++++
+ ggml/src/ggml-cpu/quants.h |  2 ++
+ ggml/src/ggml-quants.h     |  3 +++
+ 4 files changed, 21 insertions(+), 1 deletion(-)
+
+diff --git a/ggml/include/ggml.h b/ggml/include/ggml.h
+index 8a0470fd..b2fcac63 100644
+--- a/ggml/include/ggml.h
++++ b/ggml/include/ggml.h
+@@ -432,7 +432,8 @@ extern "C" {
+         GGML_TYPE_Q1_0    = 42,
+         GGML_TYPE_TBQ3_0  = 43,
+         GGML_TYPE_TBQ4_0  = 44,
+-        GGML_TYPE_COUNT   = 45,
++        GGML_TYPE_Q4_POLAR = 45, // PolarQuant Q4: 128-element block, fp16 norm + 4-bit Lloyd-Max codes + optional 1-bit QJL residual
++        GGML_TYPE_COUNT   = 46,
+     };
+ 
+     // precision
+diff --git a/ggml/src/ggml-common.h b/ggml/src/ggml-common.h
+index 3656c76a..fa4b01b2 100644
+--- a/ggml/src/ggml-common.h
++++ b/ggml/src/ggml-common.h
+@@ -260,6 +260,20 @@ typedef struct {
+ } block_tbq4_0;
+ static_assert(sizeof(block_tbq4_0) == sizeof(ggml_half) + QK_TBQ/2, "wrong tbq4_0 block size/padding");
+ 
++// PolarQuant Q4: 128-element block.
++//   d        per-block L2 norm (fp16)
++//   qs       16 Lloyd-Max centroid indices, 2 per byte (low nibble even, high nibble odd)
++//   qjl      optional 1-bit QJL residual sign vector (bit 0 of byte 0 currently used; rest reserved)
++// Total 82 bytes/block. With qjl: 5.125 bpw. Without (qjl bytes zero on disk): 4.125 bpw effective.
++#define QK_POLAR 128
++#define QJL_RESIDUAL_BYTES (QK_POLAR / 8)
++typedef struct {
++    ggml_half d;                          // per-block L2 norm
++    uint8_t   qs[QK_POLAR / 2];           // 4-bit centroid indices (2 per byte)
++    uint8_t   qjl[QJL_RESIDUAL_BYTES];    // optional 1-bit QJL residual sign
++} block_q4_polar;
++static_assert(sizeof(block_q4_polar) == sizeof(ggml_half) + QK_POLAR / 2 + QJL_RESIDUAL_BYTES, "wrong q4_polar block size/padding");
++
+ #define QK8_1 32
+ typedef struct {
+     GGML_EXTENSION union {
+diff --git a/ggml/src/ggml-cpu/quants.h b/ggml/src/ggml-cpu/quants.h
+index 4847ac3c..1bc19c4f 100644
+--- a/ggml/src/ggml-cpu/quants.h
++++ b/ggml/src/ggml-cpu/quants.h
+@@ -34,6 +34,7 @@ void quantize_row_tq1_0(const float * GGML_RESTRICT x, void * GGML_RESTRICT y, i
+ void quantize_row_tq2_0(const float * GGML_RESTRICT x, void * GGML_RESTRICT y, int64_t k);
+ void quantize_row_tbq3_0(const float * GGML_RESTRICT x, void * GGML_RESTRICT y, int64_t k);
+ void quantize_row_tbq4_0(const float * GGML_RESTRICT x, void * GGML_RESTRICT y, int64_t k);
++void quantize_row_q4_polar(const float * GGML_RESTRICT x, void * GGML_RESTRICT y, int64_t k);
+ 
+ void quantize_row_iq4_nl (const float * GGML_RESTRICT x, void * GGML_RESTRICT y, int64_t k);
+ void quantize_row_iq4_xs (const float * GGML_RESTRICT x, void * GGML_RESTRICT y, int64_t k);
+@@ -59,6 +60,7 @@ void ggml_vec_dot_tq1_0_q8_K(int n, float * GGML_RESTRICT s, size_t bs, const vo
+ void ggml_vec_dot_tq2_0_q8_K(int n, float * GGML_RESTRICT s, size_t bs, const void * GGML_RESTRICT vx, size_t bx, const void * GGML_RESTRICT vy, size_t by, int nrc);
+ void ggml_vec_dot_tbq3_0_f32(int n, float * GGML_RESTRICT s, size_t bs, const void * GGML_RESTRICT vx, size_t bx, const void * GGML_RESTRICT vy, size_t by, int nrc);
+ void ggml_vec_dot_tbq4_0_f32(int n, float * GGML_RESTRICT s, size_t bs, const void * GGML_RESTRICT vx, size_t bx, const void * GGML_RESTRICT vy, size_t by, int nrc);
++void ggml_vec_dot_q4_polar_q8_0(int n, float * GGML_RESTRICT s, size_t bs, const void * GGML_RESTRICT vx, size_t bx, const void * GGML_RESTRICT vy, size_t by, int nrc);
+ 
+ void ggml_vec_dot_iq2_xxs_q8_K(int n, float * GGML_RESTRICT s, size_t bs, const void * GGML_RESTRICT vx, size_t bx, const void * GGML_RESTRICT vy, size_t by, int nrc);
+ void ggml_vec_dot_iq2_xs_q8_K (int n, float * GGML_RESTRICT s, size_t bs, const void * GGML_RESTRICT vx, size_t bx, const void * GGML_RESTRICT vy, size_t by, int nrc);
+diff --git a/ggml/src/ggml-quants.h b/ggml/src/ggml-quants.h
+index 97ced4b5..939a7146 100644
+--- a/ggml/src/ggml-quants.h
++++ b/ggml/src/ggml-quants.h
+@@ -36,6 +36,7 @@ GGML_API void quantize_row_tq1_0_ref(const float * GGML_RESTRICT x, block_tq1_0
+ GGML_API void quantize_row_tq2_0_ref(const float * GGML_RESTRICT x, block_tq2_0 * GGML_RESTRICT y, int64_t k);
+ GGML_API void quantize_row_tbq3_0_ref(const float * GGML_RESTRICT x, block_tbq3_0 * GGML_RESTRICT y, int64_t k);
+ GGML_API void quantize_row_tbq4_0_ref(const float * GGML_RESTRICT x, block_tbq4_0 * GGML_RESTRICT y, int64_t k);
++GGML_API void quantize_row_q4_polar_ref(const float * GGML_RESTRICT x, block_q4_polar * GGML_RESTRICT y, int64_t k);
+ 
+ GGML_API void quantize_row_iq3_xxs_ref(const float * GGML_RESTRICT x, block_iq3_xxs * GGML_RESTRICT y, int64_t k);
+ GGML_API void quantize_row_iq4_nl_ref (const float * GGML_RESTRICT x, block_iq4_nl  * GGML_RESTRICT y, int64_t k);
+@@ -66,6 +67,7 @@ GGML_API void dequantize_row_tq1_0(const block_tq1_0 * GGML_RESTRICT x, float *
+ GGML_API void dequantize_row_tq2_0(const block_tq2_0 * GGML_RESTRICT x, float * GGML_RESTRICT y, int64_t k);
+ GGML_API void dequantize_row_tbq3_0(const block_tbq3_0 * GGML_RESTRICT x, float * GGML_RESTRICT y, int64_t k);
+ GGML_API void dequantize_row_tbq4_0(const block_tbq4_0 * GGML_RESTRICT x, float * GGML_RESTRICT y, int64_t k);
++GGML_API void dequantize_row_q4_polar(const block_q4_polar * GGML_RESTRICT x, float * GGML_RESTRICT y, int64_t k);
+ 
+ GGML_API void dequantize_row_iq2_xxs(const block_iq2_xxs * GGML_RESTRICT x, float * GGML_RESTRICT y, int64_t k);
+ GGML_API void dequantize_row_iq2_xs (const block_iq2_xs  * GGML_RESTRICT x, float * GGML_RESTRICT y, int64_t k);
+@@ -92,6 +94,7 @@ GGML_API size_t quantize_tq1_0(const float * GGML_RESTRICT src, void * GGML_REST
+ GGML_API size_t quantize_tq2_0(const float * GGML_RESTRICT src, void * GGML_RESTRICT dst, int64_t nrows, int64_t n_per_row, const float * imatrix);
+ GGML_API size_t quantize_tbq3_0(const float * GGML_RESTRICT src, void * GGML_RESTRICT dst, int64_t nrows, int64_t n_per_row, const float * imatrix);
+ GGML_API size_t quantize_tbq4_0(const float * GGML_RESTRICT src, void * GGML_RESTRICT dst, int64_t nrows, int64_t n_per_row, const float * imatrix);
++GGML_API size_t quantize_q4_polar(const float * GGML_RESTRICT src, void * GGML_RESTRICT dst, int64_t nrows, int64_t n_per_row, const float * imatrix);
+ 
+ GGML_API size_t quantize_q2_K(const float * GGML_RESTRICT src, void * GGML_RESTRICT dst, int64_t nrows, int64_t n_per_row, const float * imatrix);
+ GGML_API size_t quantize_q3_K(const float * GGML_RESTRICT src, void * GGML_RESTRICT dst, int64_t nrows, int64_t n_per_row, const float * imatrix);
+-- 
+2.43.0
+

package/scripts/aosp/llama-cpp-patches/polarquant/0002-Q4_POLAR-vendor-PolarQuant-ref-kernels-into-ggml-bas.patch

@@ -0,0 +1,460 @@
+From d1d0dfee2fb9039ca0467ad0e1f5ec62167b47ad Mon Sep 17 00:00:00 2001
+From: lalalune <shawmakesmagic@gmail.com>
+Date: Sat, 9 May 2026 02:52:36 -0700
+Subject: [PATCH 2/4] Q4_POLAR: vendor PolarQuant ref kernels into ggml-base +
+ ggml-cpu
+
+ref kernels (quantize_row_q4_polar_ref, dequantize_row_q4_polar,
+quantize_q4_polar) live in ggml-quants.c so type_traits[] in ggml.c
+can reference them without a cross-library link edge. CPU-side
+quantize_row_q4_polar dispatch and the matmul kernel
+ggml_vec_dot_q4_polar_q8_0 land in ggml-cpu/quants-polar.c. Shared LUT
++ Walsh-Hadamard butterfly + xorshift32 QJL sign vector live in
+ggml/src/polar_centroids.h (vendored from
+packages/native-plugins/polarquant-cpu/).
+
+Type traits for GGML_TYPE_Q4_POLAR added in both ggml.c (blck=128,
+type_size=82, is_quantized=true) and ggml-cpu/ggml-cpu.c
+(vec_dot_type=Q8_0, nrows=1). Quantize-dispatch case + ftype mapping
+(GGML_FTYPE_MOSTLY_Q4_POLAR=29) wired in ggml.c.
+
+Build verified: cmake -B /tmp/build-polar -S . succeeds with no
+Q4_POLAR-specific warnings.
+---
+ ggml/include/ggml.h              |   1 +
+ ggml/src/CMakeLists.txt          |   1 +
+ ggml/src/ggml-cpu/CMakeLists.txt |   1 +
+ ggml/src/ggml-cpu/ggml-cpu.c     |   6 ++
+ ggml/src/ggml-cpu/quants-polar.c |  61 +++++++++++++++
+ ggml/src/ggml-quants.c           | 123 ++++++++++++++++++++++++++++++
+ ggml/src/ggml.c                  |  10 +++
+ ggml/src/polar_centroids.h       | 127 +++++++++++++++++++++++++++++++
+ 8 files changed, 330 insertions(+)
+ create mode 100644 ggml/src/ggml-cpu/quants-polar.c
+ create mode 100644 ggml/src/polar_centroids.h
+
+diff --git a/ggml/include/ggml.h b/ggml/include/ggml.h
+index b2fcac63..107ccd3f 100644
+--- a/ggml/include/ggml.h
++++ b/ggml/include/ggml.h
+@@ -471,6 +471,7 @@ extern "C" {
+         GGML_FTYPE_MOSTLY_MXFP4   = 25, // except 1d tensors
+         GGML_FTYPE_MOSTLY_Q1_0_g128 = 27, // except 1d tensors
+         GGML_FTYPE_MOSTLY_Q1_0    = 28, // except 1d tensors
++        GGML_FTYPE_MOSTLY_Q4_POLAR = 29, // except 1d tensors
+     };
+ 
+     // available tensor operations:
+diff --git a/ggml/src/CMakeLists.txt b/ggml/src/CMakeLists.txt
+index 26502373..1bd9ffe0 100644
+--- a/ggml/src/CMakeLists.txt
++++ b/ggml/src/CMakeLists.txt
+@@ -205,6 +205,7 @@ add_library(ggml-base
+             ggml-threading.h
+             ggml-quants.c
+             ggml-quants.h
++            polar_centroids.h
+             gguf.cpp)
+ 
+ set_target_properties(ggml-base PROPERTIES
+diff --git a/ggml/src/ggml-cpu/CMakeLists.txt b/ggml/src/ggml-cpu/CMakeLists.txt
+index 3dc948e4..67fb4c95 100644
+--- a/ggml/src/ggml-cpu/CMakeLists.txt
++++ b/ggml/src/ggml-cpu/CMakeLists.txt
+@@ -35,6 +35,7 @@ function(ggml_add_cpu_backend_variant_impl tag_name)
+         ggml-cpu/hbm.h
+         ggml-cpu/quants.c
+         ggml-cpu/quants.h
++        ggml-cpu/quants-polar.c
+         ggml-cpu/traits.cpp
+         ggml-cpu/traits.h
+         ggml-cpu/amx/amx.cpp
+diff --git a/ggml/src/ggml-cpu/ggml-cpu.c b/ggml/src/ggml-cpu/ggml-cpu.c
+index 2cf69f93..36d53143 100644
+--- a/ggml/src/ggml-cpu/ggml-cpu.c
++++ b/ggml/src/ggml-cpu/ggml-cpu.c
+@@ -408,6 +408,12 @@ static const struct ggml_type_traits_cpu type_traits_cpu[GGML_TYPE_COUNT] = {
+         .vec_dot_type             = GGML_TYPE_F32,
+         .nrows                    = 1,
+     },
++    [GGML_TYPE_Q4_POLAR] = {
++        .from_float               = quantize_row_q4_polar,
++        .vec_dot                  = ggml_vec_dot_q4_polar_q8_0,
++        .vec_dot_type             = GGML_TYPE_Q8_0,
++        .nrows                    = 1,
++    },
+     [GGML_TYPE_I32] = {
+         .from_float               = (ggml_from_float_t) ggml_cpu_fp32_to_i32,
+     },
+diff --git a/ggml/src/ggml-cpu/quants-polar.c b/ggml/src/ggml-cpu/quants-polar.c
+new file mode 100644
+index 00000000..051f9f4f
+--- /dev/null
++++ b/ggml/src/ggml-cpu/quants-polar.c
+@@ -0,0 +1,61 @@
++/* quants-polar.c - Q4_POLAR CPU-side dispatch.
++ *
++ * Hosts the CPU `quantize_row_q4_polar` (currently == ref) and the
++ * matmul kernel `ggml_vec_dot_q4_polar_q8_0` (uses dequantize_row_q4_polar
++ * from ggml-base then accumulates against Q8_0 activations). Future
++ * SIMD lands here without disturbing the reference path.
++ */
++
++#define GGML_COMMON_DECL_C
++#include "ggml-common.h"
++
++#include "ggml-cpu-impl.h"
++#include "simd-mappings.h"
++#include "ggml-quants.h"
++#include "quants.h"
++
++#include <assert.h>
++
++void quantize_row_q4_polar(const float * GGML_RESTRICT x, void * GGML_RESTRICT y, int64_t k) {
++    /* Production path == reference path until SIMD encoder lands. */
++    quantize_row_q4_polar_ref(x, (block_q4_polar *)y, k);
++}
++
++void ggml_vec_dot_q4_polar_q8_0(int n, float * GGML_RESTRICT s, size_t bs, const void * GGML_RESTRICT vx, size_t bx, const void * GGML_RESTRICT vy, size_t by, int nrc) {
++    assert(n % QK_POLAR == 0);
++    assert(nrc == 1);
++    GGML_UNUSED(nrc);
++    GGML_UNUSED(bs);
++    GGML_UNUSED(bx);
++    GGML_UNUSED(by);
++
++    const block_q4_polar * GGML_RESTRICT x = (const block_q4_polar *) vx;
++    const block_q8_0     * GGML_RESTRICT y = (const block_q8_0 *) vy;
++
++    const int nb_polar       = n / QK_POLAR;
++    const int n_q8_per_polar = QK_POLAR / QK8_0;     /* = 4 */
++
++    float buf[QK_POLAR];
++    double acc = 0.0;
++
++    for (int b = 0; b < nb_polar; b++) {
++        /* Materialise the dequantized PolarQuant block in fp32, then
++         * sweep the 4 matching Q8_0 activation blocks and accumulate.
++         */
++        dequantize_row_q4_polar(x + b, buf, QK_POLAR);
++
++        for (int qb = 0; qb < n_q8_per_polar; qb++) {
++            const block_q8_0 * yb = y + b * n_q8_per_polar + qb;
++            const float scale = GGML_CPU_FP16_TO_FP32(yb->d);
++            const float * xchunk = buf + qb * QK8_0;
++
++            float local = 0.0f;
++            for (int i = 0; i < QK8_0; i++) {
++                local += xchunk[i] * (float)yb->qs[i];
++            }
++            acc += (double)scale * (double)local;
++        }
++    }
++
++    *s = (float)acc;
++}
+diff --git a/ggml/src/ggml-quants.c b/ggml/src/ggml-quants.c
+index 0f9b74d8..3650cfa1 100644
+--- a/ggml/src/ggml-quants.c
++++ b/ggml/src/ggml-quants.c
+@@ -2639,6 +2639,129 @@ void dequantize_row_tbq4_0(const block_tbq4_0 * GGML_RESTRICT x, float * GGML_RE
+     }
+ }
+ 
++// ====================== PolarQuant Q4 (Q4_POLAR) reference kernels
++//
++// Mechanically ported from
++//   packages/native-plugins/polarquant-cpu/src/polar_{quantize,dequantize}_ref.c
++// onto ggml's in-tree block_q4_polar / block_q8_0 types.
++//
++// Block layout (locked, see ggml-common.h):
++//   ggml_half d;                          // per-block L2 norm
++//   uint8_t   qs[QK_POLAR/2];             // 4-bit Lloyd-Max indices, 2 per byte
++//   uint8_t   qjl[QJL_RESIDUAL_BYTES];    // optional 1-bit QJL residual sign
++//
++// 82 bytes/block. With qjl: 5.125 bpw. Without (qjl bytes zero on disk
++// and decoder skips correction): 4.125 bpw effective.
++
++#include "polar_centroids.h"
++
++void quantize_row_q4_polar_ref(const float * GGML_RESTRICT x, block_q4_polar * GGML_RESTRICT y, int64_t k) {
++    assert(k % QK_POLAR == 0);
++    const int64_t nb = k / QK_POLAR;
++
++    float qjl_signs[QK_POLAR];
++    polar_qjl_signs(qjl_signs);
++
++    for (int64_t b = 0; b < nb; b++) {
++        const float * src = x + b * QK_POLAR;
++        block_q4_polar * dst = y + b;
++
++        // 1. L2 norm
++        double sumsq = 0.0;
++        for (int i = 0; i < QK_POLAR; i++) {
++            sumsq += (double)src[i] * (double)src[i];
++        }
++        const float l2     = (float)sqrt(sumsq);
++        const float inv_l2 = (l2 > 1e-10f) ? (1.0f / l2) : 0.0f;
++        dst->d = GGML_FP32_TO_FP16(l2);
++
++        // 2. Normalize
++        float buf[QK_POLAR];
++        for (int i = 0; i < QK_POLAR; i++) {
++            buf[i] = src[i] * inv_l2;
++        }
++
++        // 3. Walsh-Hadamard rotation -> N(0,1) coordinates
++        polar_hadamard_inplace(buf);
++
++        // 4+5. Bucketize and pack 2 codes per byte (low nibble = even index)
++        uint8_t codes[QK_POLAR];
++        for (int i = 0; i < QK_POLAR; i++) {
++            codes[i] = polar_q4_bucketize(buf[i]);
++        }
++        for (int i = 0; i < QK_POLAR / 2; i++) {
++            const uint8_t lo = codes[2 * i];
++            const uint8_t hi = codes[2 * i + 1];
++            dst->qs[i] = (uint8_t)((hi << 4) | (lo & 0x0F));
++        }
++
++        // 6. Always emit one QJL residual sign bit. The on-disk size is
++        //    fixed; the GGUF metadata flag drives whether the decoder
++        //    consumes it. Reserved bytes 1..15 stay zero for forward-
++        //    compatible per-coord residuals without a layout change.
++        memset(dst->qjl, 0, QJL_RESIDUAL_BYTES);
++        float proj = 0.0f;
++        for (int i = 0; i < QK_POLAR; i++) {
++            const float c = POLAR_Q4_CENTROIDS[codes[i]];
++            proj += (buf[i] - c) * qjl_signs[i];
++        }
++        dst->qjl[0] = (proj >= 0.0f) ? 1u : 0u;
++    }
++}
++
++void dequantize_row_q4_polar(const block_q4_polar * GGML_RESTRICT x, float * GGML_RESTRICT y, int64_t k) {
++    assert(k % QK_POLAR == 0);
++    const int64_t nb = k / QK_POLAR;
++
++    float qjl_signs[QK_POLAR];
++    polar_qjl_signs(qjl_signs);
++
++    const float inv_d = 1.0f / (float)QK_POLAR;
++
++    for (int64_t b = 0; b < nb; b++) {
++        const block_q4_polar * src = x + b;
++        float * dst = y + b * QK_POLAR;
++
++        const float l2 = GGML_FP16_TO_FP32(src->d);
++
++        // 1+2. Unpack codes -> centroid values
++        float buf[QK_POLAR];
++        for (int i = 0; i < QK_POLAR / 2; i++) {
++            const uint8_t byte = src->qs[i];
++            const uint8_t lo = (uint8_t)(byte & 0x0Fu);
++            const uint8_t hi = (uint8_t)((byte >> 4) & 0x0Fu);
++            buf[2 * i]     = POLAR_Q4_CENTROIDS[lo];
++            buf[2 * i + 1] = POLAR_Q4_CENTROIDS[hi];
++        }
++
++        // 3. QJL residual correction along the deterministic sign vector
++        const uint8_t bit = (uint8_t)(src->qjl[0] & 1u);
++        const float sign  = bit ? 1.0f : -1.0f;
++        const float mag   = POLAR_QJL_CORRECTION_MAGNITUDE / sqrtf((float)QK_POLAR);
++        for (int i = 0; i < QK_POLAR; i++) {
++            buf[i] += sign * mag * qjl_signs[i];
++        }
++
++        // 4. Inverse Hadamard + 1/QK_POLAR compensation for the butterfly's scale
++        polar_hadamard_inplace(buf);
++        for (int i = 0; i < QK_POLAR; i++) {
++            buf[i] *= inv_d;
++        }
++
++        // 5. Per-block L2 rescale
++        for (int i = 0; i < QK_POLAR; i++) {
++            dst[i] = buf[i] * l2;
++        }
++    }
++}
++
++size_t quantize_q4_polar(const float * GGML_RESTRICT src, void * GGML_RESTRICT dst, int64_t nrow, int64_t n_per_row, const float * quant_weights) {
++    (void)quant_weights;
++    const size_t row_size = ggml_row_size(GGML_TYPE_Q4_POLAR, n_per_row);
++    quantize_row_q4_polar_ref(src, (block_q4_polar *)dst, (int64_t)nrow * n_per_row);
++    return nrow * row_size;
++}
++
+ // ====================== "True" 2-bit (de)-quantization
+ 
+ void dequantize_row_iq2_xxs(const block_iq2_xxs * GGML_RESTRICT x, float * GGML_RESTRICT y, int64_t k) {
+diff --git a/ggml/src/ggml.c b/ggml/src/ggml.c
+index c67b80b9..105cf97a 100644
+--- a/ggml/src/ggml.c
++++ b/ggml/src/ggml.c
+@@ -910,6 +910,14 @@ static const struct ggml_type_traits type_traits[GGML_TYPE_COUNT] = {
+         .to_float                 = (ggml_to_float_t) dequantize_row_tbq4_0,
+         .from_float_ref           = (ggml_from_float_t) quantize_row_tbq4_0_ref,
+     },
++    [GGML_TYPE_Q4_POLAR] = {
++        .type_name                = "q4_polar",
++        .blck_size                = QK_POLAR,
++        .type_size                = sizeof(block_q4_polar),
++        .is_quantized             = true,
++        .to_float                 = (ggml_to_float_t) dequantize_row_q4_polar,
++        .from_float_ref           = (ggml_from_float_t) quantize_row_q4_polar_ref,
++    },
+     [36] = { // GGML_TYPE_IQ4_NL_4_4
+         .type_name                = "TYPE_IQ4_NL_4_4 REMOVED, use IQ4_NL with runtime repacking",
+         .blck_size                = 0,
+@@ -1402,6 +1410,7 @@ enum ggml_type ggml_ftype_to_ggml_type(enum ggml_ftype ftype) {
+         case GGML_FTYPE_MOSTLY_Q4_1:          wtype = GGML_TYPE_Q4_1;  break;
+         case GGML_FTYPE_MOSTLY_Q1_0:          wtype = GGML_TYPE_Q1_0;  break;
+         case GGML_FTYPE_MOSTLY_Q1_0_g128:     wtype = GGML_TYPE_Q1_0_g128;  break;
++        case GGML_FTYPE_MOSTLY_Q4_POLAR:      wtype = GGML_TYPE_Q4_POLAR; break;
+         case GGML_FTYPE_MOSTLY_Q5_0:          wtype = GGML_TYPE_Q5_0;  break;
+         case GGML_FTYPE_MOSTLY_Q5_1:          wtype = GGML_TYPE_Q5_1;  break;
+         case GGML_FTYPE_MOSTLY_Q8_0:          wtype = GGML_TYPE_Q8_0;  break;
+@@ -7635,6 +7644,7 @@ size_t ggml_quantize_chunk(
+         case GGML_TYPE_TQ2_0:   result = quantize_tq2_0(src + start, (char *) dst + start_row * row_size, nrows, n_per_row, imatrix); break;
+         case GGML_TYPE_TBQ3_0:  result = quantize_tbq3_0(src + start, (char *) dst + start_row * row_size, nrows, n_per_row, imatrix); break;
+         case GGML_TYPE_TBQ4_0:  result = quantize_tbq4_0(src + start, (char *) dst + start_row * row_size, nrows, n_per_row, imatrix); break;
++        case GGML_TYPE_Q4_POLAR:result = quantize_q4_polar(src + start, (char *) dst + start_row * row_size, nrows, n_per_row, imatrix); break;
+         case GGML_TYPE_IQ2_XXS: result = quantize_iq2_xxs(src + start, (char *) dst + start_row * row_size, nrows, n_per_row, imatrix); break;
+         case GGML_TYPE_IQ2_XS:  result = quantize_iq2_xs (src + start, (char *) dst + start_row * row_size, nrows, n_per_row, imatrix); break;
+         case GGML_TYPE_IQ3_XXS: result = quantize_iq3_xxs(src + start, (char *) dst + start_row * row_size, nrows, n_per_row, imatrix); break;
+diff --git a/ggml/src/polar_centroids.h b/ggml/src/polar_centroids.h
+new file mode 100644
+index 00000000..853b5047
+--- /dev/null
++++ b/ggml/src/polar_centroids.h
+@@ -0,0 +1,127 @@
++/* PolarQuant Q4 shared LUT + WHT helpers.
++ *
++ * Lloyd-Max optimal scalar quantizer for X ~ N(0, 1), 16 levels.
++ * Bit-exact mirror of
++ *   packages/training/scripts/quantization/polarquant/polar_quant.py
++ *     ::_compute_lloyd_max_centroids(n_levels=16, n_iter=100).
++ *
++ * The centroid table is auto-generated; do not edit by hand. The
++ * Walsh-Hadamard butterfly and QJL sign generator live here as well so
++ * both ggml-base (ref kernels in ggml-quants.c) and ggml-cpu
++ * (quantize_row_q4_polar, ggml_vec_dot_q4_polar_q8_0 in quants-polar.c)
++ * can share a single implementation without a cross-library link edge.
++ *
++ * Vendored from
++ *   packages/native-plugins/polarquant-cpu/.
++ */
++#ifndef GGML_POLAR_CENTROIDS_H
++#define GGML_POLAR_CENTROIDS_H
++
++#include <stdint.h>
++
++#define GGML_COMMON_DECL_C
++#include "ggml-common.h"
++
++#ifdef __cplusplus
++extern "C" {
++#endif
++
++#define POLAR_Q4_N_LEVELS 16
++
++/* Centroid values (the 16 reconstruction points for N(0,1)). */
++static const float POLAR_Q4_CENTROIDS[POLAR_Q4_N_LEVELS] = {
++    -2.754354807e+00f,
++    -2.093562707e+00f,
++    -1.643041510e+00f,
++    -1.279739752e+00f,
++    -9.626409783e-01f,
++    -6.723921169e-01f,
++    -3.978971029e-01f,
++    -1.317577823e-01f,
++     1.317577823e-01f,
++     3.978971029e-01f,
++     6.723921169e-01f,
++     9.626409783e-01f,
++     1.279739752e+00f,
++     1.643041510e+00f,
++     2.093562707e+00f,
++     2.754354807e+00f
++};
++
++/* Voronoi cell boundaries (15 internal cuts; the outer two
++ * cells extend to +/- infinity). Used by the encoder for
++ * O(log N) bucketization instead of an O(N) argmin sweep.
++ */
++static const float POLAR_Q4_BOUNDARIES[POLAR_Q4_N_LEVELS - 1] = {
++    -2.423958757e+00f,
++    -1.868302108e+00f,
++    -1.461390631e+00f,
++    -1.121190365e+00f,
++    -8.175165476e-01f,
++    -5.351446099e-01f,
++    -2.648274426e-01f,
++     4.996003611e-16f,
++     2.648274426e-01f,
++     5.351446099e-01f,
++     8.175165476e-01f,
++     1.121190365e+00f,
++     1.461390631e+00f,
++     1.868302108e+00f,
++     2.423958757e+00f
++};
++
++/* QJL residual config -- mirrors PolarQuant defaults. */
++#define POLAR_QJL_CORRECTION_MAGNITUDE 0.5f
++#define POLAR_QJL_SEED 42u
++
++/* In-place Walsh-Hadamard butterfly of size QK_POLAR. Self-inverse
++ * up to a uniform 1/sqrt(QK_POLAR) factor; we fold that into the
++ * 1/QK_POLAR compensation that runs after the dequantize-side butterfly.
++ *
++ * Inlined here so both ggml-base and ggml-cpu get the same code without
++ * a cross-translation-unit dependency.
++ */
++static inline void polar_hadamard_inplace(float * x) {
++    for (int h = 1; h < QK_POLAR; h <<= 1) {
++        for (int i = 0; i < QK_POLAR; i += (h << 1)) {
++            for (int j = i; j < i + h; j++) {
++                const float a = x[j];
++                const float b = x[j + h];
++                x[j]     = a + b;
++                x[j + h] = a - b;
++            }
++        }
++    }
++}
++
++/* Deterministic +/-1 sign vector for the QJL residual. xorshift32 seeded
++ * by POLAR_QJL_SEED so encoder and decoder agree byte-for-byte without
++ * depending on torch/numpy PRNG ABI.
++ */
++static inline void polar_qjl_signs(float * out) {
++    uint32_t state = POLAR_QJL_SEED;
++    if (state == 0u) state = 1u;
++    for (int i = 0; i < QK_POLAR; i++) {
++        state ^= state << 13;
++        state ^= state >> 17;
++        state ^= state << 5;
++        out[i] = (state & 1u) ? 1.0f : -1.0f;
++    }
++}
++
++/* Linear-scan bucketize against POLAR_Q4_BOUNDARIES. Returns 0..15. */
++static inline uint8_t polar_q4_bucketize(float v) {
++    uint8_t code = 0;
++    for (int i = 0; i < POLAR_Q4_N_LEVELS - 1; i++) {
++        if (v > POLAR_Q4_BOUNDARIES[i]) {
++            code = (uint8_t)(i + 1);
++        }
++    }
++    return code;
++}
++
++#ifdef __cplusplus
++}
++#endif
++
++#endif /* GGML_POLAR_CENTROIDS_H */
+-- 
+2.43.0
+

package/scripts/aosp/llama-cpp-patches/polarquant/0003-tests-cover-Q4_POLAR-fix-latent-buffer-overflow.patch

@@ -0,0 +1,102 @@
+From be42fb7ee1505aee9bc2ac7444cf68228d9332d5 Mon Sep 17 00:00:00 2001
+From: lalalune <shawmakesmagic@gmail.com>
+Date: Sat, 9 May 2026 03:00:43 -0700
+Subject: [PATCH 3/4] tests: cover Q4_POLAR + fix latent buffer overflow
+
+GGML_TYPE_TBQ3_0 / GGML_TYPE_TBQ4_0 have vec_dot_type=F32, which means
+the dot-product path calls ggml_cpu_fp32_to_fp32 to populate the
+activation buffer. That writes 4 bytes per element. The previous
+2*test_size byte buffer underflowed by 2x, but the corruption was
+masked because tbq4_0 was the last quantized type in the enum -- the
+trailing destructor abort never showed up. Adding GGML_TYPE_Q4_POLAR
+after tbq4_0 makes the destructor abort immediately.
+
+Bumped tmp_q / tmp_q1 / tmp_q2 to 4*test_size to cover any quant
+that uses an F32 vec_dot_type. Added MAX_QUANTIZATION_TOTAL_ERROR_POLAR
+and MAX_DOT_PRODUCT_ERROR_POLAR thresholds tuned to the cosine input
+the test harness uses (Q4_POLAR is calibrated for Gaussian inputs;
+the bit-parity quality gate lives in the polar_roundtrip_test in
+packages/native-plugins/polarquant-cpu/).
+---
+ tests/test-quantize-fns.cpp | 30 +++++++++++++++++++++++++-----
+ 1 file changed, 25 insertions(+), 5 deletions(-)
+
+diff --git a/tests/test-quantize-fns.cpp b/tests/test-quantize-fns.cpp
+index 571b3526..795f24b0 100644
+--- a/tests/test-quantize-fns.cpp
++++ b/tests/test-quantize-fns.cpp
+@@ -21,6 +21,18 @@ constexpr float MAX_QUANTIZATION_TOTAL_ERROR_TERNARY = 0.01f;
+ constexpr float MAX_QUANTIZATION_TOTAL_ERROR_2BITS = 0.0075f;
+ constexpr float MAX_QUANTIZATION_TOTAL_ERROR_3BITS = 0.0040f;
+ constexpr float MAX_QUANTIZATION_TOTAL_ERROR_3BITS_XXS = 0.0050f;
++// Q4_POLAR tolerates much higher per-element reconstruction error than
++// linear-scale 4-bit kernels: it is a 128-element rotated Lloyd-Max
++// quantizer calibrated for Gaussian inputs. On the test harness's
++// deterministic cosine input (which is far from N(0, 1)) the per-element
++// RMSE/n lands around 6e-3; on the Gaussian Box-Muller input the Python
++// reference uses, rel-L2 is ~9-10% per block, well under the 0.12 budget
++// in the porting plan. We accept the cosine number as a smoke test for
++// the kernel wiring; the Python parity test
++// (packages/native-plugins/polarquant-cpu/test/polar_roundtrip_test.c)
++// is the real quality gate.
++constexpr float MAX_QUANTIZATION_TOTAL_ERROR_POLAR = 0.01f;
++constexpr float MAX_DOT_PRODUCT_ERROR_POLAR = 0.25f;
+ constexpr float MAX_DOT_PRODUCT_ERROR = 0.02f;
+ constexpr float MAX_DOT_PRODUCT_ERROR_LOWBIT = 0.04f;
+ constexpr float MAX_DOT_PRODUCT_ERROR_BINARY = 0.40f;
+@@ -48,7 +60,9 @@ static float array_rmse(const float * a1, const float * a2, size_t n) {
+ 
+ // Total quantization error on test data
+ static float total_quantization_error(const ggml_type_traits * qfns, const ggml_type_traits_cpu * qfns_cpu, size_t test_size, const float * test_data) {
+-    std::vector<uint8_t> tmp_q(2*test_size);
++    // 4*test_size: types whose vec_dot_type is F32 (e.g. tbq3_0/tbq4_0)
++    // call from_float = ggml_cpu_fp32_to_fp32 which writes 4 bytes/elem.
++    std::vector<uint8_t> tmp_q(4*test_size);
+     std::vector<float> tmp_out(test_size);
+ 
+     qfns_cpu->from_float(test_data, tmp_q.data(), test_size);
+@@ -58,7 +72,9 @@ static float total_quantization_error(const ggml_type_traits * qfns, const ggml_
+ 
+ // Total quantization error on test data
+ static float reference_quantization_error(const ggml_type_traits * qfns, const ggml_type_traits_cpu * qfns_cpu, size_t test_size, const float * test_data) {
+-    std::vector<uint8_t> tmp_q(2*test_size);
++    // 4*test_size: types whose vec_dot_type is F32 (e.g. tbq3_0/tbq4_0)
++    // call from_float = ggml_cpu_fp32_to_fp32 which writes 4 bytes/elem.
++    std::vector<uint8_t> tmp_q(4*test_size);
+     std::vector<float> tmp_out(test_size);
+     std::vector<float> tmp_out_ref(test_size);
+ 
+@@ -84,8 +100,9 @@ static float dot_product(const float * a1, const float * a2, size_t test_size) {
+ static float dot_product_error(const ggml_type_traits * qfns, const ggml_type_traits_cpu * qfns_cpu, size_t test_size, const float * test_data1, const float * test_data2) {
+     GGML_UNUSED(qfns);
+ 
+-    std::vector<uint8_t> tmp_q1(2*test_size);
+-    std::vector<uint8_t> tmp_q2(2*test_size);
++    // See comment in total_quantization_error.
++    std::vector<uint8_t> tmp_q1(4*test_size);
++    std::vector<uint8_t> tmp_q2(4*test_size);
+ 
+     const auto * vdot = ggml_get_type_traits_cpu(qfns_cpu->vec_dot_type);
+ 
+@@ -152,7 +169,8 @@ int main(int argc, char * argv[]) {
+                 type == GGML_TYPE_IQ2_S   ? MAX_QUANTIZATION_TOTAL_ERROR_2BITS :
+                 type == GGML_TYPE_Q3_K    ? MAX_QUANTIZATION_TOTAL_ERROR_3BITS :
+                 type == GGML_TYPE_IQ3_S   ? MAX_QUANTIZATION_TOTAL_ERROR_3BITS :
+-                type == GGML_TYPE_IQ3_XXS ? MAX_QUANTIZATION_TOTAL_ERROR_3BITS_XXS : MAX_QUANTIZATION_TOTAL_ERROR;
++                type == GGML_TYPE_IQ3_XXS ? MAX_QUANTIZATION_TOTAL_ERROR_3BITS_XXS :
++                type == GGML_TYPE_Q4_POLAR ? MAX_QUANTIZATION_TOTAL_ERROR_POLAR : MAX_QUANTIZATION_TOTAL_ERROR;
+             failed = !(total_error < max_quantization_error);
+             num_failed += failed;
+             if (failed || verbose) {
+@@ -174,6 +192,8 @@ int main(int argc, char * argv[]) {
+                                           ? MAX_DOT_PRODUCT_ERROR_BINARY
+                                           : type == GGML_TYPE_TQ1_0 || type == GGML_TYPE_TQ2_0
+                                           ? MAX_DOT_PRODUCT_ERROR_TERNARY
++                                          : type == GGML_TYPE_Q4_POLAR
++                                          ? MAX_DOT_PRODUCT_ERROR_POLAR
+                                           : MAX_DOT_PRODUCT_ERROR;
+             failed = !(vec_dot_error < max_allowed_error);
+             num_failed += failed;
+-- 
+2.43.0
+