Plugin Chassis (PR #5651) — Reviewer's Guide

# Plugin Chassis (PR #5651) — Reviewer's Guide

This guide exists because PR #5651 is unusually large (105 files, +48,749 / −32 lines, ~150 commits over three weeks) and was built incrementally by merging several feature branches. Reading it commit-by-commit is not productive. Reading it file-by-file without context is also not productive. This doc gives you a structured walk-through so you can validate each layer independently.

**Companion documents:**
- [`ABI.md`](./ABI.md) — the plugin ABI contract: what's stable, what's tail-extensible, how versioning works.
- [`FILE_CHANGES.md`](./FILE_CHANGES.md) — file-by-file inventory (~140 files described, grouped by area).

**For plugin authors who just want to write a plugin**, see [`doc/PLUGIN_API.md`](../PLUGIN_API.md). This document is for someone reviewing the plumbing.

---

## 1. What this PR does (in one paragraph)

It introduces a **plugin chassis** — a generic ABI plus a `dlopen`-based loader inside `libproxysql.a` — and uses that chassis to ship the **first plugin**: a MySQL X Protocol terminator that builds as a separate `.so`. The chassis lives behind `#ifdef PROXYSQL40` (a new feature tier; `PROXYSQLGENAI` now implies it). Under any v3.x build (`make` with no flags, `make PROXYSQL31=1`) the chassis is **fully invisible** — no symbols, no headers, no behaviour change. The mysqlx plugin is the prototype consumer of the chassis; it auths clients, routes queries to a backend MySQL via X Protocol, optionally terminates client TLS / requires backend TLS, pools backend connections, and negotiates zstd / lz4 X Protocol compression.

```
   ┌─────────────────────────────────────────────┐
   │  proxysql binary                            │
   │  ┌──────────────────────────────────────┐   │
   │  │  libproxysql.a                       │   │
   │  │  ┌────────────────────────────────┐  │   │
   │  │  │  ProxySQL_PluginManager        │  │   │
   │  │  │  (the chassis)                 │  │   │
   │  │  │  - dlopen + RTLD_LOCAL         │  │   │
   │  │  │  - 4-phase lifecycle           │  │   │
   │  │  │  - services injection          │  │   │
   │  │  │  - admin-command dispatch      │  │   │
   │  │  │  - query-hook dispatch         │  │   │
   │  │  └────────────────────────────────┘  │   │
   │  └──────────────────────────────────────┘   │
   └─────────────────────────────────────────────┘
                        │ dlopen
                        ▼
   ┌─────────────────────────────────────────────┐
   │  ProxySQL_MySQLX_Plugin.so                  │
   │  - X Protocol auth + routing + compression  │
   │  - ~5,600 LOC handwritten                   │
   │  - protobuf 3.x (statically vendored zstd,  │
   │    lz4)                                     │
   └─────────────────────────────────────────────┘
```

The chassis is designed so the same pattern can host other plugins later (PgBouncer-protocol bridge, custom auth plugins, telemetry plugins, etc.) without reopening this PR.

---

## 2. Reading orders

Pick one based on your time budget. Each is cumulative — the 2-hour pass continues from where the 30-minute one ends.

### 30-minute pass: "is this load-bearing?"

Goal: convince yourself the chassis ABI and lifecycle are sane and the v3.x invisibility is real. Don't read mysqlx; trust that it's a consumer.

1. Read **§3 (ABI surface)** below. Cross-check against [`ABI.md`](./ABI.md).
2. Skim `include/ProxySQL_Plugin.h` — note `PROXYSQL_PLUGIN_ABI_VERSION = 3`, the descriptor struct (unchanged from ABI 2), the services struct (ABI 3 appends `register_runtime_view` at the tail).
3. Read **§4 (Four-phase lifecycle)** below.
4. Skim `lib/ProxySQL_PluginManager.cpp` lines **324–461** (load + register_schemas + abi_version gating) and **548–576** (stop_all pairs with init).
5. Check the v3.x invisibility claim:
   - `grep -L PROXYSQL40 include/ProxySQL_Plugin.h include/ProxySQL_PluginManager.h lib/ProxySQL_PluginManager.cpp` should be **empty** (every chassis file is wrapped).
   - The chassis-related deltas in `lib/Admin_Bootstrap.cpp` (line ~944) and `lib/ProxySQL_Admin.cpp` (line ~342) are inside `#ifdef PROXYSQL40` blocks.
6. Skim **§7 (Seams where consistency could break)** below — this is the list of things the incremental development pattern could have left contradictions in. Each item has a one-line check.

### 2-hour pass: "is this really designed?"

Goal: walk one full request path through the chassis and through mysqlx. Convince yourself the design is coherent end-to-end.

7. Read **§5 (Mysqlx as worked example)** below.
8. Trace one client connection through the code:
   - `Mysqlx_Thread::accept_new_connection()` (`plugins/mysqlx/src/mysqlx_thread.cpp:200`)
   - `MysqlxSession::handler()` switch (`plugins/mysqlx/src/mysqlx_session.cpp:187`)
   - `handler_capabilities_get()` → `handler_capabilities_set()` (compression + tls negotiation)
   - `handler_auth_start()` → `handle_auth_mysql41()` → `resolve_backend_target()` → `send_auth_ok()`
   - `handler_connecting_server()` (`mysqlx_session.cpp:1028`) — the backend auth handshake
   - `handler_waiting_client_msg()` / `handler_waiting_server_msg()` — the steady-state pump
9. Read **§6 (Build & CI)** below.
10. Verify a v3.0 build still works locally: `make clean && make` (with no flags). Should produce `src/proxysql` with no chassis symbols (`nm src/proxysql | grep -i plugin_manager` should be empty).

### Full day: "I'm going to vouch for this on `v3.0`."

Goal: validate the entire test corpus, run the unit tests, and exercise the e2e against a real MySQL.

11. Read [`FILE_CHANGES.md`](./FILE_CHANGES.md) end-to-end.
12. Run the test suite per the verification checklist at the end of this doc.
13. Build with `PROXYSQLGENAI=1` and run a local mysqlx connection through ProxySQL against a Docker MySQL 8.4. The CI workflow `.github/workflows/CI-mysqlx.yml` documents the commands.

---

## 3. The chassis ABI surface

The chassis is defined by **two headers** plus the loader implementation. The contract a plugin author sees is everything declared in `include/ProxySQL_Plugin.h`. The contract the proxysql core sees is everything declared in `include/ProxySQL_PluginManager.h`.

**Key types (in `include/ProxySQL_Plugin.h`):**

- `PROXYSQL_PLUGIN_ABI_VERSION` (currently `3`) — what newly-built plugins target. ABI 1 was the original 6-field descriptor; ABI 2 appends `register_schemas` for the four-phase lifecycle; ABI 3 keeps the descriptor unchanged and appends `register_runtime_view` at the tail of `ProxySQL_PluginServices` so plugins can declare admin-side projections of module state.
- `ProxySQL_PluginDescriptor` — 7-field struct returned via `extern "C" proxysql_plugin_descriptor_v1()`. The single mandatory entry point a plugin must export.
- `ProxySQL_PluginServices` — services struct injected into the plugin: table/command/query-hook registration, log helper, three DB getters, prometheus registry, runtime-view registration. Tail-append discipline preserves ABI compatibility (ABI-2 plugins compile against the smaller layout and still load on an ABI-3 core).

**The contract of the descriptor is:**
- `name` is a non-null, non-empty C string. The loader rejects anything else.
- `abi_version ∈ [1, PROXYSQL_PLUGIN_ABI_VERSION_MAX]`. The loader rejects anything else.
- `init`, `start`, `stop`: function pointers. NULL is permitted (a plugin can opt out of a phase).
- `register_schemas`: only read when `abi_version >= 2`. ABI-1 plugins skip Phase B.

**See [`ABI.md`](./ABI.md) for the full contract**, including the tail-append rule, the Phase-B-vs-Phase-D services availability matrix, the C++-ABI coupling note (`std::string` and `prometheus-cpp` are part of the contract — plugin and core must share toolchain), and the empty-source-sync invariant.

---

## 4. The four-phase plugin lifecycle

This is the single most important thing to validate. The lifecycle is implemented in `lib/ProxySQL_PluginManager.cpp` and driven from `src/main.cpp`'s startup sequence.

```
startup                                                              shutdown
┌─────┐    Phase A      Phase B           Phase C      Phase D       Phase E      ┌──────────┐
│main │ ─► load ──────► register_schemas ─► admin ────► init ──────► start ──────►│ workers  │
└─────┘    (dlopen)     (declare DDL)     init        (full         (threads      │ running  │
                                          (DDL run)    services)     spawn)       └────┬─────┘
                                                                                       │
                                                                                       ▼
                                                                                      ...
                                                                                       │
                                                                                  shutdown
                                                                                       │
                                                                  ◄─── stop ─────── teardown
                                                                  ◄─── unload (dlclose)
```

| Phase | Driver | What runs | What's available to the plugin |
|---|---|---|---|
| A | `proxysql_load_configured_plugins()` | `dlopen(RTLD_NOW \| RTLD_LOCAL)`, resolve `proxysql_plugin_descriptor_v1`, validate name + abi_version | Nothing — the plugin's code does not run yet |
| B | `proxysql_load_configured_plugins()` invokes `invoke_register_schemas_phase()` | Plugin's `register_schemas` callback runs. Plugins declare admin-schema tables and admin commands. | Phase-B services struct: `register_table`, `register_command`, `register_command_alias`, `log_message`. **DB getters return nullptr** (admin not initialized yet). Query-hook registration refuses with a warning. |
| C | `ProxySQL_Main_init_Admin_module()` calls `Admin::init()` | Admin module merges plugin-declared tables into `tables_defs_{admin,config,stats}` and runs `check_and_build_standard_tables` (single canonical DDL pass for both core + plugin tables) | Plugin code does not run; admin is materializing the schema the plugin asked for in Phase B |
| D | `proxysql_init_configured_plugins()` | Plugin's `init` callback runs | Full services struct: live DB handles, `register_query_hook` works, `get_prometheus_registry` works |
| E | `proxysql_start_configured_plugins()` | Plugin's `start` callback runs | Full services. This is where the plugin spawns threads / opens listeners. |
| (run) | worker threads | Steady-state. Plugins respond to `dispatch_admin_command` and `dispatch_query_hook` calls from the core. | Full services |
| stop | `proxysql_stop_configured_plugins()` | Plugin's `stop` callback runs | Full services |
| unload | manager destructor | `dlclose` after every plugin's `stop` returned | Nothing |

**Invariants worth verifying:**

1. **stop pairs with init**, **not** with start. If init succeeds but start fails, stop still runs. (See `lib/ProxySQL_PluginManager.cpp:548–576`. Test: `plugin_manager_unit-t.cpp:test_multi_plugin_start_failure_stops_started`.)
2. **Phase D writes commands_/hooks_; workers read them lock-free.** Phase D MUST complete before any worker thread reads via `proxysql_has_configured_plugin_query_hook`. If a future change moves listener startup before Phase D finishes, plain writes race plain reads. (Comment block at `lib/ProxySQL_PluginManager.cpp:929–949`.)
3. **The manager pointer is published BEFORE Admin::init**. `Admin::init` reads tables via `proxysql_get_plugin_manager()`. If the publish was deferred to after Phase D, the merge would see no plugin tables. (Comment block at the top of `proxysql_load_configured_plugins`.)
4. **`register_schemas` is only dereferenced when `abi_version >= 2`.** A v1 plugin's struct ends after `status_json`; reading past would be an out-of-bounds access. (Check at `lib/ProxySQL_PluginManager.cpp:407`.)
5. **The descriptor struct is tail-extensible.** A v3.x plugin compiled against ABI 2 still loads in a hypothetical future ABI 3 core (the core ignores the trailing fields it doesn't know; the plugin doesn't care). The reverse — a future plugin against an older core — is rejected at load time by the version check.

---

## 5. The mysqlx plugin as worked example

The mysqlx plugin lives entirely under `plugins/mysqlx/`. It builds as `ProxySQL_MySQLX_Plugin.so` and is loaded by the chassis at startup.

**The state machine is in `MysqlxSession`** (`plugins/mysqlx/src/mysqlx_session.cpp`, ~1,600 LOC). The 21-state `enum Status` drives a switch in `handler()` (line 187). For each Status value there's one `handler_*()` function. The state-to-handler mapping is in [`FILE_CHANGES.md`](./FILE_CHANGES.md) area H.

**A typical client flow:**

```
client                                              ProxySQL                                         backend
  │                                                    │                                              │
  ├─── TCP connect ───────────────────────────────────►│                                              │
  │                                                    ├─ accept_new_connection                       │
  │                                                    │  → MysqlxSession in CONNECTING_CLIENT        │
  ├─── CapabilitiesGet ──────────────────────────────► ├─ handler_connecting_client                   │
  │ ◄────────────────── caps reply ────────────────────┤  → X_CAPABILITIES_GET → handler_capabilities_get
  ├─── CapabilitiesSet (tls=true,                  ──► ├─ handler_capabilities_set:                   │
  │     compression=zstd_stream)                       │    parse caps, validate compression algo     │
  │ ◄──────────────────── Ok ─────────────────────────┤                                              │
  │ ◄═══ TLS handshake ═══════════════════════════════►│   X_TLS_ACCEPT_INIT / _CONT / _DONE          │
  ├─── AuthenticateStart (mysql41) ─────────────────► ├─ handler_auth_start                           │
  │ ◄────────────── AuthenticateContinue ─────────────┤    (challenge sent)                           │
  ├─── AuthenticateContinue (scramble) ──────────────►├─ handler_auth_challenge_response:             │
  │                                                    │     verify scramble (CRYPTO_memcmp)           │
  │                                                    │     resolve_backend_target() ─── route ──────┤
  │ ◄────────────────── AuthenticateOk ───────────────┤                                              │
  │                                                    │   WAITING_CLIENT_XMSG                        │
  ├─── StmtExecute ─────────────────────────────────► ├─ handler_waiting_client_msg                   │
  │                                                    │     → CONNECTING_SERVER if no backend yet    │
  │                                                    │     → handler_connecting_server: connect +   │
  │                                                    │       backend auth state machine ────────────►├─── X auth handshake
  │                                                    │     → forward_to_backend  ───────────────────►├─── StmtExecute
  │                                                    │                                              │ ◄── Resultset rows
  │                                                    │   handler_waiting_server_msg                 │
  │                                                    │     → forward_frame_to_client                │
  │                                                    │     → send_to_client_compressed              │
  │ ◄────────────── (zstd-compressed) Resultset ──────┤                                              │
  │                                                    │   WAITING_CLIENT_XMSG                        │
  │                                                    │  (loop)                                      │
```

The mysqlx plugin demonstrates every chassis affordance:

- **Phase B** — `mysqlx_register_schemas` declares 8 admin-schema tables (`mysqlx_users`, `mysqlx_routes`, `mysqlx_backend_endpoints`, `mysqlx_variables`, plus their `runtime_*` admin-side projections and `stats_mysqlx_*` tables), 16 admin commands (`LOAD MYSQLX USERS TO RUNTIME` and the 7 cousins, plus `SAVE` variants and aliases like `FROM MEMORY` / `FROM MEM` / `TO RUN`), and four runtime-view refresh callbacks via `services.register_runtime_view` (one per `runtime_mysqlx_<X>` table).
- **Phase D** — `mysqlx_init` performs disk-to-memory sync of the mysqlx tables on first boot, then loads the in-memory `MysqlxConfigStore` directly from the editable admin tables via four `install_<X>_from_admin` calls.
- **Phase E** — `mysqlx_start` clamps the thread-pool size, drives the listener reconciler from `MysqlxConfigStore::snapshot_active_routes()`, and spawns N worker threads.
- **Admin command dispatch** — `LOAD MYSQLX <X> TO RUNTIME` lands on a callback that invokes `MysqlxConfigStore::install_<X>_from_admin`; `SAVE MYSQLX <X> [FROM RUNTIME] TO MEMORY` invokes `MysqlxConfigStore::save_<X>_to_admin_table`. The disk-tier variants (LOAD/SAVE FROM/TO DISK) remain a plain BEGIN/DELETE/INSERT/COMMIT between configdb and admindb.
- **Runtime-view projections** — when admin runs `SELECT * FROM runtime_mysqlx_users` (or one of the four cousins), the chassis fires the registered refresh callback, which calls `MysqlxConfigStore::project_<X>_to_runtime_view(admindb)` to wipe and refill the admin table from current module state.
- **Identity callbacks** — each `MysqlxSession` is given an `identity_lookup_` closure that calls back into `MysqlxConfigStore::resolve_identity()` for the username the client sends.

If you can convince yourself the chassis can host the mysqlx plugin coherently, the chassis is in good shape.

---

## 6. Build & CI tier-flag wiring

`PROXYSQL40=1` must propagate consistently through five Makefile layers. **A mismatch silently changes the descriptor / services struct layouts** between core and plugin — the link succeeds, the first dispatch corrupts memory.

```
top-level Makefile
   │  PSQL40 := -DPROXYSQL40 (when PROXYSQL40=1)
   │
   ├─► lib/Makefile     (compiles ProxySQL_PluginManager.cpp into libproxysql.a)
   ├─► src/Makefile     (links libproxysql.a)
   ├─► plugins/mysqlx/Makefile   (compiles ProxySQL_MySQLX_Plugin.so)
   └─► test/tap/tests/unit/Makefile  (compiles plugin_*_unit-t / mysqlx_*_unit-t)
                                      adds -DMYSQLX_TEST_BUILD on top
```

**Verifications:**

- `nm src/proxysql | grep -i ProxySQL_PluginManager` is **empty** when built without `PROXYSQL40=1`.
- `nm src/proxysql | grep -i ProxySQL_PluginManager` is **non-empty** when built with `PROXYSQLGENAI=1` (which implies `PROXYSQL40=1`).
- The mysqlx plugin Makefile fails fast if libprotobuf is **not** 3.x (see `plugins/mysqlx/Makefile:38–51`). Already saw this fire on CI in commit `9f5ed235b` — the `cleanbuild` path triggered the check on a v3.0 box without libprotobuf-dev. Fixed by skipping the check on `clean`/`cleanall`.
- CI workflow `.github/workflows/CI-mysqlx.yml` invokes `make` inside `plugins/mysqlx` with **all five tier flags** explicitly: `PROXYSQL40=1 PROXYSQL31=1 PROXYSQLFFTO=1 PROXYSQLTSDB=1 PROXYSQLGENAI=1`. This was added in commit `df7e335e2` after the tests/CI agent caught that the workflow was building the plugin with a different set of tier flags than the cached `src/proxysql` had been built with — exactly the silent struct-layout-mismatch hazard.

---

## 7. Seams where consistency could break

These are the places where the incremental development pattern could have left contradictions — a comment that says one thing while the code does another, two paths that claim to do the same job, an `#ifdef` that forgot to flip somewhere. Each item has a one-line verification.

| # | Concern | Verification |
|---|---|---|
| 1 | The five Makefile layers all see the same tier flags | `make clean && PROXYSQLGENAI=1 make` succeeds; `nm src/proxysql` and `nm plugins/mysqlx/ProxySQL_MySQLX_Plugin.so` both contain `ProxySQL_PluginManager` symbols. |
| 2 | `PROXYSQL40` macro gates every chassis source | `git grep -l 'class ProxySQL_PluginManager\|register_schemas\|invoke_register_schemas_phase' include lib src` — every hit should be inside an `#ifdef PROXYSQL40` block (or in a header that is itself wrapped). |
| 3 | The chassis is invisible to v3.x | `make clean && make` (no flags) — no chassis-related symbols in the binary. |
| 4 | The four-phase order in main.cpp matches the lifecycle invariant | `src/main.cpp` lines around 1570: `LoadConfiguredPlugins` → `ProxySQL_Main_init_Admin_module` → `InitConfiguredPlugins` → `StartConfiguredPlugins`. No reordering. |
| 5 | The descriptor `register_schemas` is gated by `abi_version >= 2` | `lib/ProxySQL_PluginManager.cpp:407` — the read is inside `if (descriptor->abi_version >= 2u)`. |
| 6 | `materialize_plugin_tables()` is gone (was a no-op disguised as load-bearing) | `git grep materialize_plugin_tables` returns only the explanatory comment in `Admin_Bootstrap.cpp:~1351`. |
| 7 | Plugin getters in `ProxySQL_Admin.cpp` are gated | `proxysql_plugin_get_admindb/configdb/statsdb` definitions are inside `#ifdef PROXYSQL40` (line ~342). |
| 8 | Test-only forgery setters do not leak into production | `nm plugins/mysqlx/ProxySQL_MySQLX_Plugin.so | grep inject_identity_for_test` is **empty**. (The test build defines `MYSQLX_TEST_BUILD`; the production build does not.) |
| 9 | `MysqlxConnection::reset()` scrubs backend buffers between pool reuses | `plugins/mysqlx/src/mysqlx_connection.cpp:39–52`: calls `backend_ds_.clear_io_buffers()` (added in commit `4bd4b462b`). |
| 10 | `Mysqlx_Thread::run()` drains sessions on shutdown | `plugins/mysqlx/src/mysqlx_thread.cpp:run()` post-loop walks `sessions_` and calls `shutdown_notify_client()`. |
| 11 | `inet_pton` failure is fatal in `start_connect()` | `plugins/mysqlx/src/mysqlx_connection.cpp:53–67`: returns `-1` with `state_=ERROR_STATE` on parse failure. |
| 12 | `groups.json` lint passes locally | `python3 test/tap/groups/check_groups.py` returns OK (no missing-from-groups, no built-but-unregistered). |
| 13 | All 32 plugin/mysqlx tests carry `@proxysql_min_version:4.0` | `grep -E '^\s*"(mysqlx_\|plugin_\|test_mysqlx_)' test/tap/groups/groups.json \| wc -l` should be 32. (The total tag count `grep -c '@proxysql_min_version:4.0'` includes pre-existing GenAI/AI/MCP tests and is much higher — that's expected, not a bug.) |
| 14 | TLS_PASSTHROUGH (dead code) is gone | `git grep TLS_PASSTHROUGH plugins/` returns nothing. |
| 15 | The dead `#else /* !PROXYSQL40 */` branches in PluginManager are gone | `git grep '!PROXYSQL40' include lib` — no inner `#else` branches inside whole-file PROXYSQL40 wraps. |
| 16 | The orphaned `infras.lst` and `docker-compose-mysqlx.yml` are gone | `ls test/tap/groups/mysqlx-e2e/infras.lst test/infra/docker-compose-mysqlx.yml` returns "No such file or directory" for both. |
| 17 | `g_active_plugin_manager_mutex` is a `std::shared_mutex` (not `std::mutex`) | `grep 'std::shared_mutex g_active_plugin_manager_mutex' lib/ProxySQL_PluginManager.cpp`. |

If all 17 of these check, the consistency concern is largely answered — the pieces line up.

---

## 8. Commit topology

The PR has ~150 commits, but they group naturally into five intent-bands. You don't need to review individually; you need to know which commits drove which design.

### Band 1 — chassis foundation (early April)
The original design + initial implementation. These set the ABI shape.

- `7e1a12b8f` feat: add generic plugin ABI and loader
- `da7e18271` fix: align plugin loader ABI and tests
- `f13463d33` feat(plugin-abi): Step 2.2 — four-phase plugin lifecycle
- `cd15afdd1e` feat: support plugin-owned admin tables and commands
- `2430516600` fix: reject conflicting plugin registrations

If you only read 5 commits, read these.

### Band 2 — mysqlx baseline (early-to-mid April)
The X Protocol plugin built on top of the chassis. ~80 commits, mostly within `plugins/mysqlx/`. These are the "feature work" commits and are best reviewed by reading the result, not the patches — see [`FILE_CHANGES.md`](./FILE_CHANGES.md) area A–L.

### Band 3 — mysqlx hardening (mid-to-late April)
Bug fixes from running the plugin against a real MySQL 8.4. These are the small surgical commits — the kind you'd cherry-pick if you needed to backport a fix.

- `7e2f7828a` fix(mysqlx): make sync transactions atomic on execute() failure
- `c78d7b859` fix(mysqlx): reconcile bind-address changes
- `dd131b0aa` fix(mysqlx): reconcile listeners at startup and on LOAD ROUTES TO RUNTIME
- `3e8c3da9d` fix(mysqlx): preserve backend TLS state past auth handshake
- `82fe27f4b` fix(mysqlx): sync empty source tables to overwrite stale rows
- `e09908179` fix(mysqlx): record stats on unreachable guard
- `76aafdac6` fix(mysqlx): harden check_connect() poll and getsockopt handling
- `bbe812251` fix(mysqlx): reject auth without credential_lookup and release pooled fd

### Band 4 — chassis hardening + invisibility audit (April 19–22)
After the original design landed, an audit found symbols leaking into v3.x and dead code paths. These commits clean that up.

- `3ba92815f` fix(plugin-chassis): make chassis fully invisible in v3.x builds
- `ab9d5a103` fix(plugin-chassis): address deep-review findings
- `6edde821c` fix(glovars): forward-declare debug_level for direct header consumers
- `e20876a45` fix(tests): repair pre-existing mysqlx test build breakage
- `f10411692` fix(plugin-mgr): serialize lifecycle and always reset manager on stop

### Band 5 — review-driven cleanup (this week, April 27)
The independent review of PR #5651 produced 19 findings. These commits address them.

- `9f5ed235b` fix(build,test groups): unblock CI on plugin-chassis (B3 + #6 + lint)
- `4bd4b462b` fix(mysqlx): three blocking protocol/pool correctness bugs (B1 + B2 + parse)
- `04bccec51` chore(plugin-chassis): tighten gating, drop dead paths, gate forgery setters (#9 + #10 + #12 + #13)
- `df7e335e2` fix(ci,infra): pass PROXYSQL40 to plugin build, remove orphaned infra files (#5 + #4 + #18)
- `55e90d1a7` fix(plugin-chassis,mysqlx): chassis read-path scaling, graceful shutdown, hardening (#7 + #8 + #11 + #15 + #16 + #17)

For a complete walk through each finding and how it was addressed, see `git log --grep="PR #5651" --since=2026-04-26`.

---

## 9. Verification checklist

A reviewer who can tick each box has done a fair-quality review of this PR.

### Build
- [ ] `make clean && make` (no flags) succeeds on a v3.0-grade box. `nm src/proxysql | grep ProxySQL_PluginManager` is empty.
- [ ] `make clean && PROXYSQLGENAI=1 make` succeeds. `nm src/proxysql | grep ProxySQL_PluginManager` is non-empty.
- [ ] `cd plugins/mysqlx && PROXYSQL40=1 PROXYSQL31=1 PROXYSQLFFTO=1 PROXYSQLTSDB=1 PROXYSQLGENAI=1 make` produces `ProxySQL_MySQLX_Plugin.so`.
- [ ] `nm plugins/mysqlx/ProxySQL_MySQLX_Plugin.so | grep -i 'visibility\|hidden'` shows hidden visibility default; only `proxysql_plugin_descriptor_v1` exported.

### ABI hygiene
- [ ] 32 plugin/mysqlx test entries carry `@proxysql_min_version:4.0`; verify with the grep in §7 row 13.
- [ ] `python3 test/tap/groups/lint_groups_json.py` returns OK.
- [ ] `python3 test/tap/groups/check_groups.py` returns OK.

### Tests
- [ ] `make build_tap_tests` succeeds with `PROXYSQLGENAI=1`.
- [ ] At least one of the larger unit tests passes: `cd test/tap/tests/unit && ./mysqlx_robustness_unit-t` should report 74/74.
- [ ] `./plugin_lifecycle_unit-t`, `./plugin_dispatch_unit-t`, `./plugin_query_hook_unit-t` all green.

### Sanity (manual)
- [ ] Start ProxySQL with `PROXYSQLGENAI=1` build, `plugins=("/path/to/ProxySQL_MySQLX_Plugin.so")` in proxysql.cnf, and the mysqlx_users / mysqlx_routes tables populated.
- [ ] Connect with `mysqlsh --mysqlx --uri user@host:6033` (or X-Protocol port from your config). A handshake completes; a `SELECT 1` round-trips.
- [ ] `SELECT * FROM stats_mysqlx_routes` shows non-zero counters.
- [ ] `SHUTDOWN` — the client sees a clean disconnect, not a TCP RST. (This validates `shutdown_notify_client()` from §7 row 10.)

### Consistency seams (§7)
- [ ] All 17 rows from §7 verified.

If a reviewer ticks all of the above, this PR has been substantively reviewed.

---

## Appendix: how this PR was assembled

For full transparency, the mysqlx plugin started as PR #5593 (`ProtocolX` branch) targeting `v3.0` directly. The chassis started as PR #5651 (`plugin-chassis` branch) also targeting `v3.0`. PR #5593 was retargeted onto `plugin-chassis` and merged there, so the chassis PR (#5651) now carries both. This is why the commit history includes a mix of "chassis foundation" commits and "mysqlx feature/fix" commits — they were two PRs unified into one for review purposes, since the mysqlx plugin doesn't make sense without the chassis underneath it.

The independent review described in Band 5 above produced this guide as a deliverable.