metal: add per-token flush/op counters for Issue #16 investigation

tq_metal_diag_get/reset return how many times tq_metal_batch_flush()
hit the GPU sync path during a run, plus the total ops in those flushes.
The PPL tool now prints flushes/token + ops/flush at the end of an eval
when TQ_HAS_METAL is set.

This gives empirical answers (instead of guesses) to:
  - How often does the dispatch path actually fire?
  - How many ops are amortized per flush?

Used during Issue #16 investigation to confirm the Q8_0 weight path
never enters Metal batch mode (0 flushes/token), narrowing the
slowdown source to Q4_K (gguf_w*) and the fused tq_metal_forward_layer
Q4 path.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: unamedkr

src/backend/metal/tq_metal_dispatch.m

@@ -667,6 +667,22 @@ void tq_metal_batch_begin(void) {
  * Flush the current batch: end encoding, commit, wait, copy results.
  * Safe to call when no batch is active (no-op).
  */
+/* Diagnostic counters (Issue #16: dispatch overhead investigation).
+ * Reset by callers via tq_metal_diag_reset(); read via tq_metal_diag_get().
+ * No-op when batch path isn't taken — overhead is one atomic add per flush. */
+static unsigned long g_metal_flush_count    = 0;
+static unsigned long g_metal_flush_op_count = 0; /* total dispatched ops across flushes */
+
+void tq_metal_diag_reset(void) {
+    g_metal_flush_count = 0;
+    g_metal_flush_op_count = 0;
+}
+
+void tq_metal_diag_get(unsigned long* flushes, unsigned long* ops) {
+    if (flushes) *flushes = g_metal_flush_count;
+    if (ops)     *ops     = g_metal_flush_op_count;
+}
+
 void tq_metal_batch_flush(void) {
     if (!tq_batch.active) return;
 
@@ -677,6 +693,8 @@ void tq_metal_batch_flush(void) {
         }
 
         if (tq_batch.cmd_buf && tq_batch.n_copies > 0) {
+            g_metal_flush_count    += 1;
+            g_metal_flush_op_count += (unsigned long)tq_batch.n_copies;
             [tq_batch.cmd_buf commit];
             [tq_batch.cmd_buf waitUntilCompleted];
 

tools/quant.c

@@ -510,6 +510,21 @@ int main(int argc, char** argv) {
         /* Machine-parseable */
         fprintf(stderr, "PPL_CSV:%d,%.6f,%.4f\n", n_eval, avg_nll, perplexity);
 
+#ifdef TQ_HAS_METAL
+        {
+            extern void tq_metal_diag_get(unsigned long*, unsigned long*);
+            unsigned long n_flushes = 0, n_ops = 0;
+            tq_metal_diag_get(&n_flushes, &n_ops);
+            if (n_flushes > 0 && n_eval > 0) {
+                fprintf(stderr, "Metal diag: %lu flushes, %lu ops total, "
+                                "%.1f flushes/token, %.1f ops/flush\n",
+                        n_flushes, n_ops,
+                        (double)n_flushes / (double)n_eval,
+                        (double)n_ops / (double)n_flushes);
+            }
+        }
+#endif
+
         /* JSON output (--json flag) */
         if (json_output) {
             const char* kv_name = kv_type < TQ_TYPE_COUNT ? tq_type_name(kv_type) : "fp32";