Unit test infrastructure: Glo* stubs, init helpers, and smoke test

CLAUDE.md

@@ -0,0 +1,156 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+ProxySQL is a high-performance, protocol-aware proxy for MySQL (and forks like MariaDB, Percona Server) and PostgreSQL. Written in C++17, it provides connection pooling, query routing, caching, and monitoring. Licensed under GPL.
+
+## Build Commands
+
+The build system is GNU Make-based with a three-stage pipeline: `deps` → `lib` → `src`.
+
+```bash
+# Full release build (auto-detects -j based on nproc/hw.ncpu)
+make
+
+# Debug build (-O0, -ggdb, -DDEBUG)
+make debug
+
+# Build with ASAN (requires no jemalloc)
+NOJEMALLOC=1 WITHASAN=1 make build_deps_debug && make debug && make build_tap_test_debug
+
+# Build TAP tests (requires proxysql binary built first)
+make build_tap_tests          # release
+make build_tap_test_debug     # debug
+
+# Clean
+make clean                    # clean src/lib
+make cleanall                 # clean everything including deps
+
+# Build packages
+make packages
+```
+
+### Feature Tiers
+
+The same codebase produces three product tiers via feature flags:
+
+| Tier | Flag | Version | Adds |
+|------|------|---------|------|
+| Stable | (default) | v3.0.x | Core proxy |
+| Innovative | `PROXYSQL31=1` | v3.1.x | FFTO, TSDB |
+| AI/MCP | `PROXYSQLGENAI=1` | v4.0.x | GenAI, MCP, Anomaly Detection (requires Rust toolchain) |
+
+`PROXYSQLGENAI=1` implies `PROXYSQL31=1`, which implies `PROXYSQLFFTO=1` and `PROXYSQLTSDB=1`.
+
+### Build Flags
+
+- `NOJEMALLOC=1` — disable jemalloc
+- `WITHASAN=1` — enable AddressSanitizer (requires `NOJEMALLOC=1`)
+- `WITHGCOV=1` — enable code coverage
+- `PROXYSQLCLICKHOUSE=1` — enabled by default in current builds
+
+## Testing
+
+Tests use TAP (Test Anything Protocol) with Docker-based backend infrastructure.
+
+```bash
+# Build and run all TAP tests
+make build_tap_tests
+cd test/tap && make
+
+# Run specific test groups
+cd test/tap/tests && make
+cd test/tap/tests_with_deps && make
+
+# Test infrastructure (Docker environments)
+# Located in test/infra/ with docker-compose configs for:
+# mysql57, mysql84, mariadb10, pgsql16, pgsql17, clickhouse23, etc.
+```
+
+Test files follow the naming pattern `test_*.cpp` or `*-t.cpp` in `test/tap/tests/`.
+
+## Architecture
+
+### Build Pipeline
+
+```
+deps/          → builds 25+ vendored dependencies as static libraries
+lib/           → compiles ~121 .cpp files into libproxysql.a
+src/main.cpp   → links against libproxysql.a to produce the proxysql binary
+```
+
+### Dual-Protocol Design
+
+MySQL and PostgreSQL share parallel class hierarchies with the same architecture but protocol-specific implementations:
+
+| Layer | MySQL | PostgreSQL |
+|-------|-------|------------|
+| Protocol | `MySQL_Protocol` | `PgSQL_Protocol` |
+| Session | `MySQL_Session` | `PgSQL_Session` |
+| Thread | `MySQL_Thread` | `PgSQL_Thread` |
+| HostGroups | `MySQL_HostGroups_Manager` | `PgSQL_HostGroups_Manager` |
+| Monitor | `MySQL_Monitor` | `PgSQL_Monitor` |
+| Query Processor | `MySQL_Query_Processor` | `PgSQL_Query_Processor` |
+| Logger | `MySQL_Logger` | `PgSQL_Logger` |
+
+### Core Components
+
+- **Admin Interface** (`ProxySQL_Admin.cpp`, `Admin_Handler.cpp`) — SQL-based configuration via SQLite3 backend. Supports runtime config changes without restart. Schema versions tracked in `ProxySQL_Admin_Tables_Definitions.h`.
+- **HostGroups Manager** — Routes connections based on hostgroup assignments. Supports master-slave, Galera, Group Replication, and Aurora topologies.
+- **Query Processor** — Parses queries, matches against routing rules, handles query caching via `Query_Cache`.
+- **Monitor** — Health-checks backends for replication lag, read-only status, and connectivity.
+- **Threading** — Event-based I/O using libev. `Base_Thread` base class with protocol-specific thread managers.
+- **HTTP/REST** (`ProxySQL_HTTP_Server`, `ProxySQL_RESTAPI_Server`) — Metrics and management endpoints.
+
+### Key Dependencies (in deps/)
+
+- `jemalloc` — memory allocator
+- `sqlite3` — admin config storage
+- `mariadb-client-library` — MySQL protocol
+- `postgresql` — PostgreSQL protocol
+- `re2`, `pcre` — regex engines
+- `libev` — event loop
+- `libinjection` — SQL injection detection
+- `lz4`, `zstd` — compression
+- `curl`, `libmicrohttpd`, `libhttpserver` — HTTP
+- `prometheus-cpp` — metrics
+- `libscram` — SCRAM authentication
+
+### Conditional Components
+
+- **FFTO** (Fast Forward Traffic Observer) — `MySQLFFTO.cpp`, `PgSQLFFTO.cpp`
+- **TSDB** — Time-series metrics with embedded dashboard
+- **GenAI/MCP** — `GenAI_Thread`, `MCP_Thread`, `LLM_Bridge`, `Anomaly_Detector`, tool handlers
+- **ClickHouse** — Native ClickHouse protocol support
+
+## Code Layout
+
+- `include/` — All headers (.h/.hpp). Include guards use `#ifndef __CLASS_*_H`.
+- `lib/` — Core library sources (~121 files). One class per file typically.
+- `src/main.cpp` — Entry point, daemon init, thread spawning (~95K lines).
+- `test/tap/` — TAP test framework and tests.
+- `test/infra/` — Docker-based test environments.
+- `.github/workflows/` — CI/CD pipelines (selftests, TAP tests, package builds, CodeQL).
+
+## Agent Guidelines
+
+See `doc/agents/` for detailed guidance on working with AI coding agents:
+- `doc/agents/project-conventions.md` — ProxySQL-specific rules (directories, build, test harness, git workflow)
+- `doc/agents/task-assignment-template.md` — Template for writing issues assignable to AI agents
+- `doc/agents/common-mistakes.md` — Known agent failure patterns with prevention and detection
+
+### Unit Test Harness
+
+Unit tests live in `test/tap/tests/unit/` and link against `libproxysql.a` via a custom test harness. Tests must use `test_globals.h` and `test_init.h` — see `doc/agents/project-conventions.md` for the full pattern.
+
+## Coding Conventions
+
+- Class names: `PascalCase` with protocol prefixes (`MySQL_`, `PgSQL_`, `ProxySQL_`)
+- Member variables: `snake_case`
+- Constants/macros: `UPPER_SNAKE_CASE`
+- C++17 required; conditional compilation via `#ifdef PROXYSQLGENAI`, `#ifdef PROXYSQL31`, etc.
+- Performance-critical code — consider implications of changes to hot paths
+- RAII for resource management; jemalloc for allocation
+- Pthread mutexes for synchronization; `std::atomic<>` for counters

doc/agents/README.md

@@ -0,0 +1,9 @@
+# Agent Guidelines for ProxySQL
+
+This directory contains guidance for AI coding agents (Claude Code, GitHub Copilot, etc.) working on the ProxySQL codebase.
+
+| Document | Purpose |
+|----------|---------|
+| [project-conventions.md](project-conventions.md) | ProxySQL-specific rules: where files go, how to build, branch model |
+| [task-assignment-template.md](task-assignment-template.md) | Template for writing issues that agents can execute correctly |
+| [common-mistakes.md](common-mistakes.md) | Known failure patterns and how to prevent them |

doc/agents/common-mistakes.md

@@ -0,0 +1,148 @@
+# Common Mistakes by AI Coding Agents
+
+Patterns observed across multiple AI agent interactions on the ProxySQL codebase, with root cause analysis and prevention strategies.
+
+## 1. Wrong Branch Target
+
+**Symptom:** PR targets `v3.0` (main) instead of the feature branch.
+
+**Root cause:** Agents prioritize technical content over administrative instructions. Even when branch info is present in the issue, agents often skim past it while focusing on code requirements, then use heuristics (e.g., most recent branch, default branch) to fill the gap they don't realize they have.
+
+**Prevention:** Place git workflow instructions **at the very top** of the issue, before the technical description. Agents read top-down with decreasing attention — administrative details buried after exciting code specs will be skipped.
+
+```
+### FIRST: Git workflow (do this before reading anything else)
+- Create branch `v3.0-XXXX` from `v3.0-5473`
+- PR target: `v3.0-5473`
+```
+
+**Detection:** Check `gh pr view <number> --json baseRefName` after PR creation.
+
+---
+
+## 2. Reimplemented Functions in Test Files
+
+**Symptom:** Test file contains copy-pasted reimplementations of the functions under test. Tests validate the copy, not the real production code.
+
+**Root cause:** Agent doesn't know the build system links tests against `libproxysql.a`, so it creates standalone tests that don't depend on the library.
+
+**Prevention:**
+- Explain that tests link against `libproxysql.a` (the real functions are available at link time)
+- Add to DO NOT list: "Do NOT reimplement extracted functions in the test file"
+- Provide the Makefile rule that shows the linking
+
+**Detection:** `grep -c "static.*calculate_eviction\|static.*evaluate_pool" test_file.cpp` — if > 0, functions were reimplemented.
+
+---
+
+## 3. Test Files in Wrong Directory
+
+**Symptom:** Test placed in `test/tap/tests/` (E2E test directory) instead of `test/tap/tests/unit/` (unit test directory).
+
+**Root cause:** Agent sees existing test files in `test/tap/tests/` and follows that pattern. Doesn't know about the `unit/` subdirectory.
+
+**Prevention:** Specify the exact file path including directory in the issue deliverables.
+
+**Detection:** `ls test/tap/tests/*unit*` should return nothing — unit tests belong in `test/tap/tests/unit/`.
+
+---
+
+## 4. Manual TAP Symbol Stubs
+
+**Symptom:** Test file manually defines `noise_failures`, `noise_failure_mutex`, `stop_noise_tools()`, `get_noise_tools_count()`.
+
+**Root cause:** Agent compiles `tap.cpp` which references these symbols. Without the harness, the agent must define them. This is a signal the agent isn't using the harness.
+
+**Prevention:**
+- Explain that `test_globals.cpp` already provides all TAP stubs
+- Add to DO NOT list: "Do NOT define noise_failures or stop_noise_tools"
+
+**Detection:** `grep -c "noise_failures\|stop_noise_tools" test_file.cpp` — if > 0, harness not used.
+
+---
+
+## 5. Merged Instead of Rebased
+
+**Symptom:** PR diff includes dozens of unrelated files because the agent ran `git merge <upstream>` into its branch.
+
+**Root cause:** Agent's default strategy for incorporating upstream changes is merge. This creates a merge commit that brings all upstream changes into the PR diff.
+
+**Prevention:** Explicit instruction: "Use `git rebase`, NOT `git merge`."
+
+**Detection:** `git log --merges <branch> --not <base>` — any merge commits indicate merging.
+
+---
+
+## 6. Circular Include Dependencies
+
+**Symptom:** Production code compiles on the agent's machine (or doesn't get tested) but fails in CI or on other platforms with "unknown type name" errors.
+
+**Root cause:** ProxySQL has circular include chains (`proxysql.h` → `cpp.h` → `MySQL_HostGroups_Manager.h` → `Base_HostGroups_Manager.h` → `proxysql.h`). Placing new declarations in these headers can result in the declarations being invisible depending on include order.
+
+**Prevention:**
+- Create standalone headers with their own include guards (e.g., `ConnectionPoolDecision.h`)
+- Explicitly warn about the circular chain in the issue
+- Require `make build_lib -j4` as a verification step
+
+**Detection:** Compilation failure with "unknown type name" for a type that clearly exists in a header.
+
+---
+
+## 7. Modified Existing Test Files Instead of Creating New Ones
+
+**Symptom:** Agent adds tests to an existing test file instead of creating a new one for the new feature.
+
+**Root cause:** Agent sees a test file for a related component and assumes new tests belong there.
+
+**Prevention:** Specify the exact test file name in the issue: "Create `test/tap/tests/unit/my_feature_unit-t.cpp`."
+
+---
+
+## 8. Didn't Verify Compilation
+
+**Symptom:** PR contains code that doesn't compile. Agent submitted without building.
+
+**Root cause:** Some agents don't have access to the build environment, or don't run the build as part of their workflow.
+
+**Prevention:**
+- Add explicit verification step: "`make build_lib -j4` must exit with code 0"
+- Add to acceptance criteria as a hard requirement
+
+---
+
+## 9. Overly Broad Changes
+
+**Symptom:** Agent refactors callers, updates documentation, fixes unrelated bugs, or "improves" code outside the task scope.
+
+**Root cause:** Agent optimizes for perceived quality/completeness and makes changes it considers beneficial.
+
+**Prevention:**
+- Explicitly scope: "Only modify `<list of files>`"
+- Add: "Do not refactor code outside the scope of this task"
+- Add: "Do not fix pre-existing issues you notice — file separate issues for those"
+
+---
+
+## Summary: Red Flags in Agent PRs
+
+Quick checks to run on any agent-generated PR:
+
+```bash
+# Wrong base branch?
+gh pr view <PR> --json baseRefName -q '.baseRefName'
+
+# Test in wrong directory?
+gh pr diff <PR> | grep "^+++ b/test/tap/tests/[^u]"
+
+# Reimplemented functions?
+gh pr diff <PR> | grep "^+static.*calculate_\|^+static.*evaluate_\|^+static.*should_"
+
+# Manual TAP stubs?
+gh pr diff <PR> | grep "^+.*noise_failures\|^+.*stop_noise_tools"
+
+# Merge commits?
+gh pr view <PR> --json commits --jq '.commits[].messageHeadline' | grep -i merge
+
+# Unrelated files changed?
+gh pr diff <PR> | grep "^+++ b/" | grep -v "<expected_files_pattern>"
+```