volvoxai 0.1.0

package/docs/README.md

@@ -0,0 +1,22 @@
+# VolvoxAI Documentation
+
+This directory holds the detailed reference material for VolvoxAI. Start with
+the root [README](../README.md) for the short overview, then use these pages for
+the implementation details.
+
+| Doc | What it covers |
+| --- | --- |
+| [quickstart.md](quickstart.md) | Build commands, browser bundle, CLI smoke tests, and model download commands. |
+| [browser-runtime.md](browser-runtime.md) | Browser and Node runtime tiers: WebNN, WebGPU, WASM SIMD, and CPU. |
+| [native-runtime.md](native-runtime.md) | Native C engine, native CLI tasks, GPU/NPU backends, Android cross-build notes. |
+| [model-format.md](model-format.md) | Volvox blueprint format, safetensors loading, tensor layout, precision policy. |
+| [models.md](models.md) | Regenerating EfficientDet, TinyStories, and TinyReceiptKIE model packages. |
+| [operation_list.md](operation_list.md) | Per-op backend support matrix for browser and native runtimes. |
+| [testing.md](testing.md) | WebGPU op tests, native smoke tests, parity checks, and known validation limits. |
+| [roadmap.md](roadmap.md) | Current gaps and planned work. |
+| [textbook/](textbook/README.md) | A from-scratch walkthrough of inference, tensors, models, and engine internals. |
+| [efficientdet_tflite_vs_volvoxai.md](efficientdet_tflite_vs_volvoxai.md) | EfficientDet Lite0 CPU/GPU benchmark methodology and results. |
+| [microkernel_optimization_guide.md](microkernel_optimization_guide.md) | CPU Conv/GEMM microkernel notes. |
+| [operator_fusion_patterns.md](operator_fusion_patterns.md) | Graph fusion patterns applied by the native optimizer. |
+| [xnnpack_optimization_guide.md](xnnpack_optimization_guide.md) | XNNPACK-style packing and indirection reference notes. |
+

package/docs/browser-runtime.md

@@ -0,0 +1,87 @@
+# Browser and Node Runtime
+
+VolvoxAI exposes one browser API and chooses the best available execution tier at
+initialization and compilation time.
+
+## Backend Selection
+
+`VolvoxAI.init(preferredBackend = "auto", wasmUrl = "./volvoxai.wasm")` accepts a
+backend string or a strict ordered backend array.
+
+| Call | Behavior |
+| --- | --- |
+| `VolvoxAI.init()` or `VolvoxAI.init("auto")` | Try WebNN, then WebGPU, then WASM, then CPU. |
+| `VolvoxAI.init("webnn")` | Prefer WebNN; fall back to WASM then CPU. |
+| `VolvoxAI.init("webgpu")` | Prefer WebGPU; fall back to WASM then CPU. |
+| `VolvoxAI.init("wasm")` | Skip WebNN/WebGPU and use WASM with CPU fallback. |
+| `VolvoxAI.init("cpu")` | CPU only. |
+| `VolvoxAI.init(["wasm", "webgpu"])` | Strict allow-list. No CPU fallback unless `"cpu"` is included. |
+
+Array mode is strict. `init()` throws if none of the listed backends initializes,
+and `compile()` throws if the initialized backends cannot compile the graph.
+
+## Tier 1: WebNN
+
+`WebNNEngine` builds an `MLGraphBuilder` graph and dispatches through
+`navigator.ml`. The browser may route work to NPU, GPU, or CPU depending on the
+platform, browser flags, drivers, and supported ops.
+
+Current WebNN coverage:
+
+`MatMul`/`Linear`/`Gemm`, `Add`, `Mul`, `ReLU`, `GELU`, `SiLU`/`Swish`,
+`Sigmoid`, `Softmax`, `Reshape`/`Flatten`, `LayerNorm`, `Conv2D`,
+`Embedding`, and `SDPA` decomposed into lower-level WebNN ops.
+
+Missing low-cost mappings include `Sub`, `Div`, `Tanh`, `Clip`, `LeakyReLU`,
+`PReLU`, `HardSwish`, `HardSigmoid`, `Transpose`, `Concat`, `Split`, `Slice`,
+`Pad`, `Where`, `Gather`, `Cast`, `Expand`, reductions, pooling, batch norm,
+resampling, and `ConvTranspose2D`.
+
+Missing composite formulas include `RMSNorm`, `CrossSDPA`, `CrossAttention`,
+`LogSoftmax`, `DequantizeLinear`, and `Conv1D` as a reshape plus `conv2d`.
+
+WebNN requires a secure context such as HTTPS or localhost. Chromium WebNN support
+is evolving and often needs `--enable-features=WebMachineLearningNeuralNetwork`.
+`deviceType: "npu"` is not proof that an NPU executed the work; unsupported
+accelerators can fall back to CPU.
+
+Useful references:
+
+- W3C WebNN: <https://www.w3.org/TR/webnn/>
+- WebNN compatibility: <https://webnn.io/en/api-reference/browser-compatibility/api>
+- Chromium flags: <https://webnn.io/en/api-reference/browser-compatibility/chrome-flags>
+
+## Tier 2: WebGPU
+
+`GraphExecutor` allocates one GPU buffer per tensor, uploads weights once, and
+builds one compute pipeline per node. `execute()` replays the prebuilt pipelines in
+one command encoder, flushing every 20 dispatches.
+
+The WebGPU path keeps the model resident on the GPU and returns a `GPUBuffer`.
+Current limitation: it returns the final node's first output rather than a map of
+all `graph.outputNames`. Multi-output models should use WASM/CPU until WebGPU
+multi-output readback is implemented.
+
+Unsupported WebGPU shader nodes currently warn and skip, leaving the output buffer
+unwritten. Use [operation_list.md](operation_list.md) to check whether a model's
+ops are safe on WebGPU.
+
+## Tier 3: WASM SIMD
+
+`WasmEngine` loads the freestanding `volvoxai.wasm` module built from
+`native/kernels.c`. It uses a bump allocator over `__heap_base` and places graph
+tensors in WASM linear memory. Some pointwise, broadcast, and gather operations are
+handled in JS over typed-array views into the same heap.
+
+## Tier 4: CPU
+
+`CPUEngine` is the pure-JS reference backend. It is slower, but dependency-free and
+useful for debugging, fallback behavior, and cross-tier correctness checks.
+
+## Node Import Behavior
+
+`ShaderLibrary.js` statically imports every `shaders/*.wgsl` file as text, which
+only works in the bundled browser build. It is not re-exported from `js/index.js`.
+`GraphExecutor` lazy-loads it only when the WebGPU path compiles, so plain Node
+imports can use WASM/CPU without a bundler.
+

package/docs/efficientdet_tflite_vs_volvoxai.md

@@ -0,0 +1,445 @@
+# EfficientDet Lite0: TFLite vs VolvoxAI Native
+
+This document compares MediaPipe EfficientDet Lite0 int8, float16-source, and
+float32-source packages on the Linux CPU path, and records the Android
+OpenGL GPU result for the float32 package.
+
+Machine/runtime:
+
+- CPU: AMD Ryzen 5 5600U with Radeon Graphics, single-thread runs
+- TFLite: `/tmp/benchmark_model`, XNNPACK enabled, `--num_threads=1`,
+  `--warmup_runs=2`, `--num_runs=20`
+- VolvoxAI: `./native/volvoxai detect ... --num_threads 1 --warmup_runs 2
+  --num_runs 20`
+- Test image for VolvoxAI: `/tmp/volvox_dog.jpg`
+
+Android GPU runtime:
+
+- Device: Samsung SM-A528N, Qualcomm `lahaina`, Adreno 642L, Android SDK 34
+- TFLite: `/data/local/tmp/benchmark_model`, GPU delegate, `--gpu_backend=gl`,
+  `--warmup_runs=2`, `--num_runs=20`
+- VolvoxAI: Android arm64 build, `--opengl`, OpenGL ES 3.2,
+  `--warmup_runs 2`, `--num_runs 20`
+- Test image for VolvoxAI: `/data/local/tmp/volvoxai_gltest/volvoxai_object_test.jpg`
+
+Important caveats:
+
+- TFLite `benchmark_model` measures generated tensor input. VolvoxAI `detect forward`
+  is the graph forward after the image input is loaded.
+- VolvoxAI prints raw detection tensors. This is a speed comparison, not a validation of
+  MediaPipe postprocessing/NMS correctness.
+- TFLite GPU defaults to allowing lower precision. The Android section includes both
+  the default GPU delegate result and a `--gpu_precision_loss_allowed=false` rerun.
+- The TFLite float16 model uses float32 input/output and XNNPACK reports F32 kernels on
+  CPU. It is not an FP16 CPU-kernel speed test.
+- Direct TFLite export keeps VolvoxAI tensors in NHWC and stores Conv weights in
+  TFLite-native layouts: regular Conv2D as `OHWI`, depthwise Conv2D as `1HWO`. The
+  native CPU path prepares a per-node HWIO/HWCM compute cache at engine init, so the
+  artifact stays TFLite-shaped without making the hot Conv loops stride through OHWI.
+- The float16-source package stores floating weights as safetensors `F16`. Native CPU
+  keeps the artifact half-sized and prepares a widened Conv weight cache at engine init
+  for the default `cpu-f16w-pack` path. On this AVX2 CPU this is not native FP16
+  arithmetic; it is half-size storage plus one-time FP32 widening.
+
+## Artifacts
+
+| Package | Source TFLite | Optional ONNX | Volvox weights | Volvox config | Volvox graph contract |
+| --- | ---: | ---: | ---: | ---: | --- |
+| `models/efficientdet_lite0_int8` | `4.4M` | `4.0M` | `3.4M` | `148K` | direct TFLite NHWC, quantized `QConv2D`, `I8` OHWI/1HWO weights |
+| `models/efficientdet_lite0_fp16` | `7.0M` | `13M` | `6.4M` | `108K` | direct TFLite NHWC, `F16` OHWI/1HWO weights |
+| `models/efficientdet_lite0_fp32` | `14M` | `13M` | `13M` | `108K` | direct TFLite NHWC, FP32 OHWI/1HWO weights |
+
+The fp16-source package preserves half-precision storage in safetensors:
+
+```text
+models/efficientdet_lite0_fp16/model.safetensors  F16 tensors 253
+Conv2D backend=cpu-f16w-pack
+```
+
+The int8 package preserves quantized Conv nodes and quantization metadata:
+
+```text
+models/efficientdet_lite0_int8/config.json  QConv2D 182
+models/efficientdet_lite0_fp16/config.json  Conv2D  182
+models/efficientdet_lite0_fp32/config.json  Conv2D  182
+models/efficientdet_lite0_fp16/config.json  Transpose 0
+models/efficientdet_lite0_fp32/config.json  Transpose 0
+```
+
+The direct TFLite configs report:
+
+```text
+internal_layout=NHWC
+conv_weight_layout=OHWI
+depthwise_weight_layout=1HWO
+```
+
+The first Conv/QConv weights match TFLite shapes:
+
+```text
+w0 regular Conv2D   (32, 3, 3, 3)    # OHWI
+w2 depthwise Conv2D (1, 3, 3, 32)    # 1HWO
+```
+
+The int8 VolvoxAI debug log confirms the quantized path is active:
+
+```text
+QConv2D backend=cpu-qconv
+QConv2D backend=cpu-qconv-f32
+QConv2D backend=cpu-qconv-f32
+```
+
+Most Conv nodes keep quantized NHWC activations and int8 weights with int32
+accumulation/requantization. Some output-head nodes produce FP32 output
+where the graph leaves the quantized island.
+
+## Export Commands
+
+Download the float models:
+
+```bash
+mkdir -p models/efficientdet_lite0_fp16 models/efficientdet_lite0_fp32
+
+curl -L -o models/efficientdet_lite0_fp16/efficientdet_lite0_float16.tflite \
+  https://storage.googleapis.com/mediapipe-models/object_detector/efficientdet_lite0/float16/latest/efficientdet_lite0.tflite
+
+curl -L -o models/efficientdet_lite0_fp32/efficientdet_lite0_float32.tflite \
+  https://storage.googleapis.com/mediapipe-models/object_detector/efficientdet_lite0/float32/latest/efficientdet_lite0.tflite
+
+cp models/efficientdet_lite0_int8/labels.txt models/efficientdet_lite0_fp16/labels.txt
+cp models/efficientdet_lite0_int8/labels.txt models/efficientdet_lite0_fp32/labels.txt
+```
+
+Export TFLite directly to VolvoxAI:
+
+```bash
+python3 tools/export_safetensors.py \
+  --model models/efficientdet_lite0_fp16/efficientdet_lite0_float16.tflite \
+  --out models/efficientdet_lite0_fp16/model.safetensors
+
+python3 tools/export_safetensors.py \
+  --model models/efficientdet_lite0_fp32/efficientdet_lite0_float32.tflite \
+  --out models/efficientdet_lite0_fp32/model.safetensors
+```
+
+The exporter auto-selects `F16` storage for the float16 TFLite model because its constant
+weights are stored as half precision. Use `--weight-dtype float32` to force FP32 artifact
+storage, or `--weight-dtype float16` to force half-precision storage.
+
+The direct float exports reported:
+
+```text
+float16: TFLite ops=516 folded_dequantize=253 lowered_nodes=263 optimized_nodes=262 weights=253
+float32: TFLite ops=263 folded_dequantize=0 lowered_nodes=263 optimized_nodes=262 weights=253
+```
+
+## Benchmark Commands
+
+TFLite:
+
+```bash
+/tmp/benchmark_model \
+  --graph=models/efficientdet_lite0_int8/efficientdet_lite0.tflite \
+  --num_threads=1 \
+  --use_xnnpack=true \
+  --warmup_runs=2 \
+  --num_runs=20 \
+  --min_secs=0 \
+  --max_secs=30
+```
+
+Add `--enable_op_profiling=true --op_profiling_output_mode=stdout` to reproduce
+the TFLite op-sum tables below.
+
+VolvoxAI:
+
+```bash
+clang -O3 -mavx2 -mfma -pthread -Inative \
+  native/cJSON.c native/safetensors.c native/kernels.c native/quant_cpu_opt.c \
+  native/conv_f32_opt.c native/tensor_f32_opt.c native/engine_runtime.c \
+  native/engine.c native/image_io.c native/kie_runtime.c native/vulkan_engine.c \
+  native/opengl_engine.c native/tokenizer.c native/nnapi_engine.c native/main.c \
+  -o native/volvoxai -lm -ldl
+
+./native/volvoxai detect models/efficientdet_lite0_int8 \
+  --image input0=/tmp/volvox_dog.jpg \
+  --image-normalize raw-255 \
+  --boxes boxes \
+  --scores scores \
+  --max-det 5 \
+  --num_threads 1 \
+  --warmup_runs 2 \
+  --num_runs 20
+```
+
+Add `--debug` to reproduce the VolvoxAI op-sum and load/init tables below.
+
+For the float-source packages, replace the model directory with
+`models/efficientdet_lite0_fp16` or `models/efficientdet_lite0_fp32`.
+
+Android TFLite OpenGL GPU:
+
+```bash
+adb shell 'cd /data/local/tmp && ./benchmark_model \
+  --graph=/data/local/tmp/tflite_gltest/efficientdet_lite0_float32.tflite \
+  --use_gpu=true \
+  --gpu_backend=gl \
+  --warmup_runs=2 \
+  --warmup_min_secs=0 \
+  --num_runs=20 \
+  --min_secs=0 \
+  --max_secs=60 \
+  --num_threads=1'
+```
+
+Add `--gpu_precision_loss_allowed=false` for the strict fp32 GPU rerun.
+
+Android VolvoxAI OpenGL ES:
+
+```bash
+adb shell 'cd /data/local/tmp/volvoxai_gltest && ./volvoxai detect \
+  models/efficientdet_lite0_fp32 \
+  --image input0=volvoxai_object_test.jpg \
+  --image-normalize raw-255 \
+  --boxes boxes \
+  --scores scores \
+  --max-det 3 \
+  --opengl \
+  --warmup_runs 2 \
+  --num_runs 20'
+```
+
+## High-Level Result
+
+Headline timings are timed first/avg/min/max after two warmup runs. They omit
+TFLite op profiling and VolvoxAI `--debug` logging.
+
+| Source model | TFLite first | TFLite avg | TFLite min | TFLite max | VolvoxAI first | VolvoxAI avg | VolvoxAI min | VolvoxAI max | Gap by avg |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
+| int8 | `26.758 ms` | `25.943 ms` | `25.234 ms` | `28.078 ms` | `37.589 ms` | `38.299 ms` | `37.589 ms` | `39.431 ms` | `1.48x` |
+| float16 | `25.816 ms` | `25.857 ms` | `25.115 ms` | `27.432 ms` | `29.486 ms` | `30.895 ms` | `29.486 ms` | `32.473 ms` | `1.19x` |
+| float32 | `25.355 ms` | `26.024 ms` | `25.004 ms` | `26.950 ms` | `29.361 ms` | `30.805 ms` | `29.361 ms` | `33.251 ms` | `1.18x` |
+
+TFLite op profiling and VolvoxAI `--debug` summaries from matching 20-run jobs.
+For VolvoxAI, the op row averages the last 20 debug summary blocks and excludes
+the two warmup forwards.
+
+| Source model | TFLite profiled op avg | TFLite nodes | VolvoxAI debug op avg | VolvoxAI nodes |
+| --- | ---: | ---: | ---: | ---: |
+| int8 | `25.579 ms` | `196` | `37.078 ms` | `265` |
+| float16 | `26.326 ms` | `193` | `30.770 ms` | `262` |
+| float32 | `26.255 ms` | `193` | `30.987 ms` | `262` |
+
+Read:
+
+- TFLite/XNNPACK is faster on one CPU thread. The int8 gap is `1.48x`.
+- VolvoxAI int8 uses quantized `QConv2D` execution, but it is slower than the
+  float-source native path in this run.
+- TFLite float16 and float32 are almost the same on CPU because XNNPACK reports F32 kernels
+  for both.
+- VolvoxAI float16-source stores `F16` weights and defaults to a prepared
+  `cpu-f16w-pack` path. Direct half-weight consumption is not used for this
+  comparison because this AVX2 CPU lacks native FP16 arithmetic.
+- The direct TFLite paths have no ONNX-derived Transpose nodes. The float
+  graph has 262 nodes, and the int8 graph is direct NHWC TFLite with 265 nodes.
+- No-debug single-thread runs are `38.299 ms` for int8 and about `31 ms` for the
+  float-source packages.
+
+## TFLite Op Sums
+
+These come from TFLite operator-profiling runs with the same thread/warmup/run counts.
+The total row is the profiler's 20-run average, not the sum of rounded table rows.
+
+| Op group | int8 | float16-source | float32-source |
+| --- | ---: | ---: | ---: |
+| Pointwise 1x1 / GEMM, 101 calls | `17.912 ms` | `18.009 ms` | `18.052 ms` |
+| Depthwise Conv, 80 calls | `4.418 ms` | `5.197 ms` | `5.124 ms` |
+| Stem Conv, 1 call | `1.758 ms` | `1.019 ms` | `0.951 ms` |
+| Unary / activation | `0.871 ms` | `1.019 ms` | `1.043 ms` |
+| Copy / tensor movement | `0.153 ms` | `0.711 ms` | `0.708 ms` |
+| Binary Add | `0.103 ms` | `0.150 ms` | `0.159 ms` |
+| ResizeNearest | `0.072 ms` | `0.085 ms` | `0.086 ms` |
+| MaxPool | `0.017 ms` | `0.059 ms` | `0.056 ms` |
+| Quantize | `0.208 ms` | n/a | n/a |
+| Total profiled op avg | `25.579 ms` | `26.326 ms` | `26.255 ms` |
+
+TFLite int8 uses XNNPACK quantized kernels:
+
+```text
+Fully Connected (NC, QS8, QC8W) GEMM
+Convolution (NHWC, QC8) DWConv
+Convolution (NHWC, QC8) IGEMM
+```
+
+The float16-source and float32-source TFLite runs both report:
+
+```text
+Fully Connected (NC, F32) GEMM
+Convolution (NHWC, F32) DWConv
+Convolution (NHWC, F32) IGEMM
+```
+
+## VolvoxAI Op Sums
+
+These average the 20 timed `--debug` forwards; the two warmup forwards are excluded.
+
+| Op group | int8 package | float16-source package | float32-source package |
+| --- | ---: | ---: | ---: |
+| Conv aggregate | `QConv2D 34.80 ms` | `Conv2D cpu-f16w-pack 28.85 ms` | `Conv2D cpu-pack 28.93 ms` |
+| Concat | `1.25 ms` | `1.37 ms` | `1.49 ms` |
+| Add | `0.42 ms` | `0.33 ms` | `0.34 ms` |
+| MaxPool2D | `0.40 ms` | `0.14 ms` | `0.14 ms` |
+| ResizeNearest2D | `0.04 ms` | `0.08 ms` | `0.08 ms` |
+| QuantizeLinear | `0.18 ms` | n/a | n/a |
+| DequantizeLinear | aliased after Concat | n/a | n/a |
+| Total profiled op avg | `37.08 ms` | `30.77 ms` | `30.99 ms` |
+
+VolvoxAI load/init timings from representative debug runs:
+
+| Package | load weights | build graph | engine init |
+| --- | ---: | ---: | ---: |
+| int8 | `3.523 ms` | `8.906 ms` | `14.800 ms` |
+| float16-source | `7.216 ms` | `7.503 ms` | `36.135 ms` |
+| float32-source | `12.595 ms` | `6.758 ms` | `40.580 ms` |
+
+The float-source engine init includes layout/precision preparation:
+
+```text
+fp16: prepack_conv weights=182 biases=182 pointwise_packs=101 igemm_indirs=1 19.720 ms
+fp32: prepack_conv weights=182 biases=0   pointwise_packs=101 igemm_indirs=1 19.535 ms
+```
+
+## CPU Gap
+
+The int8 VolvoxAI path is a real quantized graph island for most Conv nodes. It uses a
+wide AVX2 pointwise tile plus an exact AVX2 byte-dot path for `input_zero_point = -128`
+pointwise layers, vectorized same-quant MaxPool2D, vectorized contiguous QuantizeLinear,
+and aliasing for final no-op DequantizeLinear nodes after Concat. It is not an
+XNNPACK-class CPU implementation.
+
+One-thread blockers:
+
+1. Pointwise and depthwise microkernels are much simpler than XNNPACK. They need
+   architecture-specific dot-product paths, better unrolling, and better cache blocking.
+2. Depthwise Conv needs XNNPACK-style indirection/bounds handling to remove per-MAC
+   padding math.
+3. Weight packing exists, but it is not microkernel-specific enough for VNNI/AVX512 or
+   ARM `sdot`/`udot`.
+4. Some graph tails leave the quantized island and produce FP32 output tensors.
+5. The fp16-source export preserves `F16` weight storage and prepares those weights once
+   for CPU Conv2D. This follows the guide's weight-preparation principle on AVX2, but
+   true hardware FP16 arithmetic requires ARM FP16, AVX512-FP16, or a GPU path.
+
+## Native GPU Status
+
+OpenGL waits at the end of `engine_forward`, so reported forward time includes real
+queued GPU work rather than only CPU-side dispatch/enqueue time.
+
+Linux fp32 EfficientDet Lite0 timings on the Ryzen 5 5600U machine:
+
+| Engine | Backend | Avg, warmup 2 / runs 20 | Notes |
+| --- | --- | ---: | --- |
+| VolvoxAI | CPU fp32 | `29.990 ms` | `--num_threads 1` |
+| VolvoxAI | Vulkan graph | `45.523 ms` | AMD RADV Renoir, vector/tiled Conv2D shaders |
+| VolvoxAI | OpenGL graph | `40.256 ms` | AMD Renoir Mesa, vector/tiled Conv2D shaders |
+
+Representative corrected debug summaries show that most elapsed time is in the final GPU
+wait, not in CPU enqueue:
+
+```text
+OpenGL: engine_forward 46.823 ms, GPUWait 40.46 ms, Conv2D enqueue 3.42 ms
+Vulkan: engine_forward 43.100 ms, GPUWait 39.41 ms, Conv2D enqueue 1.67 ms
+```
+
+## Android OpenGL GPU Result
+
+Run on the attached SM-A528N / Adreno 642L device with the float32 EfficientDet Lite0
+package.
+
+| Engine | Backend | First | Avg | Min | Max | Gap vs TFLite default |
+| --- | --- | ---: | ---: | ---: | ---: | ---: |
+| TFLite | GPU delegate, OpenGL, default precision | `138.365 ms` | `127.211 ms` | `90.464 ms` | `139.163 ms` | `1.00x` |
+| TFLite | GPU delegate, OpenGL, fp32 strict | `120.499 ms` | `130.962 ms` | `120.499 ms` | `139.626 ms` | `1.03x` |
+| VolvoxAI | OpenGL ES 3.2, vector/tiled Conv2D | `118.918 ms` | `144.332 ms` | `118.918 ms` | `153.026 ms` | `1.13x` |
+
+The OpenGL run uses Naga-generated GLES shaders for depthwise, pointwise, and the
+EfficientDet stem Conv2D, and is `1.13x` slower than the TFLite OpenGL default-precision
+baseline.
+
+TFLite log confirmation:
+
+```text
+Replacing 263 out of 263 node(s) with delegate (TfLiteGpuDelegateV2)
+yielding 1 partitions for subgraph 0
+Initialized OpenGL-based API
+Created 1 GPU delegate kernels
+Inference (avg): 127211 us
+```
+
+VolvoxAI log confirmation:
+
+```text
+[VolvoxAI GPU] OpenGL Compute initialized:
+Qualcomm / Adreno (TM) 642L / OpenGL ES 3.2
+[bench] detect: first=118.918 avg=144.332 min=118.918 max=153.026 ms
+```
+
+The `--debug` run is not the benchmark average, but it identifies where the time goes:
+
+```text
+[debug] engine_forward nodes=262 159.649 ms
+[debug] --- op time summary (by total) ---
+[debug]   GPUWait            114.84 ms  (n=1)
+[debug]   Conv2D              11.90 ms  (n=182)
+[debug]   Add                  2.51 ms  (n=42)
+[debug]   MaxPool2D            0.76 ms  (n=14)
+[debug]   ResizeNearest2D      0.62 ms  (n=12)
+[debug]   Concat               0.18 ms  (n=2)
+[debug]   Reshape              0.13 ms  (n=10)
+[debug]   TOTAL              130.94 ms
+```
+
+## Android OpenGL Gap Analysis
+
+The OpenGL path selects vectorized and tiled Naga-generated GLES shaders for
+EfficientDet's dominant Conv shapes:
+
+```text
+stem Conv2D:       conv2DRegularC3Out16
+depthwise Conv2D:  conv2DDepthwise8
+pointwise Conv2D:  conv2DPointwise16Tile
+head pointwise:    conv2DPointwise8Vec4 / conv2DPointwise8Vec2
+fallback Conv2D:   conv2D / conv2DPointwise8
+```
+
+The `1.13x` gap is small but not a measurement artifact. The VolvoxAI OpenGL path is a
+per-node compute backend, while TFLite's GPU delegate compiles the whole graph into one
+delegated partition.
+
+Reasons for the gap:
+
+1. TFLite delegates the whole EfficientDet graph into one GPU partition and creates one
+   GPU delegate kernel. VolvoxAI executes the exported graph as 262 native nodes.
+2. VolvoxAI dispatches each graph op separately. Each dispatch binds buffers, launches
+   compute, and inserts a shader-storage memory barrier. That is correct but expensive for
+   hundreds of small mobile-GPU kernels.
+3. Each op creates a small uniform parameter buffer for that dispatch. This is minor
+   compared with `GPUWait`, but it is unnecessary per-node overhead.
+4. The OpenGL backend has only kernel-level specialization. It does not fuse larger
+   EfficientDet blocks across Add/Resize/Conv boundaries the way a graph delegate can.
+5. The Android OpenGL path runs fp32 GLES compute shaders. TFLite default precision can use
+   lower precision, but the strict fp32 TFLite rerun is `130.962 ms`, so precision
+   alone is not the reason.
+
+The debug profile's `Conv2D 11.90 ms` row is CPU-side enqueue/profile time, not real GPU
+compute time. The real queued GPU execution appears in `GPUWait 114.84 ms`; enqueue-only
+OpenGL timing omits it.
+
+Work to consistently match or beat the TFLite GPU delegate:
+
+1. Fuse EfficientDet blocks at graph compile time instead of dispatching every op as a
+   separate shader.
+2. Remove per-dispatch memory barriers when a graph-level dependency schedule can prove
+   ordering.
+3. Reuse persistent parameter buffers or push constants/equivalent small-uniform storage.
+4. Add a fp16/mobile GPU path and benchmark it separately from fp32.