queue-aiops 0.2.0__tar.gz → 0.2.2__tar.gz

{queue_aiops-0.2.0 → queue_aiops-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: queue-aiops
-Version: 0.2.0
+Version: 0.2.2
 Summary: Governed AI-ops for redis + rabbitmq: memory-pressure/latency/queue-backlog/connection-churn RCAs, slowlog and SCAN-budgeted big-key sampling, queues/policies/nodes, and governed writes (config set, client kill, purge/delete queue, policies) with a built-in governance harness (audit, budget, undo, risk tiers)
 Author-email: wei <zhouwei008@gmail.com>
 License-Expression: MIT
@@ -192,17 +192,20 @@ queue-aiops analyze memory|latency|backlog|churn
 
 ## Verification status
 
-**Mock-validated; not yet run against live brokers.** The full test suite runs against
-mocked clients (no live broker needed): every module imports, every MCP tool carries the
-governance marker, the four flagship RCAs are unit-tested against synthetic telemetry,
-and reversible writes are asserted to record the correct inverse undo descriptor. The
-REST paths and `INFO` field names are modelled from the public docs of both platforms
-and have not been exercised against a real broker.
-
-Both platforms are trivially self-hostable, so `queue-aiops doctor` against a local lab
-redis instance / rabbitmq broker (management plugin enabled) is the quickest live check.
-[docs/VERIFICATION.md](docs/VERIFICATION.md) is the full checklist a live run must
-satisfy.
+**Live-verified against Redis 7.4.9 and RabbitMQ 3.13.7 (2026-07-19/20).**
+Connectivity, every Redis read (cross-checked against `redis-cli` ground truth), all
+four analyses, and the full governance loop (real `redis_config_set` → audit row →
+undo restoring the prior value) were exercised against a real server. That run found
+and fixed a real defect: integer quantities — key counts, client counts, byte totals —
+were rendered as floats (`202.0` keys), which equality assertions cannot catch.
+
+The RabbitMQ group is now verified end-to-end too — reads cross-checked against
+`rabbitmqadmin`, and `set_policy` → `undo_apply` closing on the live broker. **Redis
+cluster/sentinel topologies and AUTH/TLS connections** remain unverified.
+
+[docs/VERIFICATION.md](docs/VERIFICATION.md) records exactly what was checked and what
+is still open. `queue-aiops doctor` is the fastest live check.
+
 
 ## Contributing
 

{queue_aiops-0.2.0 → queue_aiops-0.2.2}/README.md

@@ -175,17 +175,20 @@ queue-aiops analyze memory|latency|backlog|churn
 
 ## Verification status
 
-**Mock-validated; not yet run against live brokers.** The full test suite runs against
-mocked clients (no live broker needed): every module imports, every MCP tool carries the
-governance marker, the four flagship RCAs are unit-tested against synthetic telemetry,
-and reversible writes are asserted to record the correct inverse undo descriptor. The
-REST paths and `INFO` field names are modelled from the public docs of both platforms
-and have not been exercised against a real broker.
-
-Both platforms are trivially self-hostable, so `queue-aiops doctor` against a local lab
-redis instance / rabbitmq broker (management plugin enabled) is the quickest live check.
-[docs/VERIFICATION.md](docs/VERIFICATION.md) is the full checklist a live run must
-satisfy.
+**Live-verified against Redis 7.4.9 and RabbitMQ 3.13.7 (2026-07-19/20).**
+Connectivity, every Redis read (cross-checked against `redis-cli` ground truth), all
+four analyses, and the full governance loop (real `redis_config_set` → audit row →
+undo restoring the prior value) were exercised against a real server. That run found
+and fixed a real defect: integer quantities — key counts, client counts, byte totals —
+were rendered as floats (`202.0` keys), which equality assertions cannot catch.
+
+The RabbitMQ group is now verified end-to-end too — reads cross-checked against
+`rabbitmqadmin`, and `set_policy` → `undo_apply` closing on the live broker. **Redis
+cluster/sentinel topologies and AUTH/TLS connections** remain unverified.
+
+[docs/VERIFICATION.md](docs/VERIFICATION.md) records exactly what was checked and what
+is still open. `queue-aiops doctor` is the fastest live check.
+
 
 ## Contributing
 

queue_aiops-0.2.2/RELEASE_NOTES.md

@@ -0,0 +1,29 @@
+# Release notes — queue-aiops 0.2.2
+
+Previous release: 0.2.1.
+
+## Fixed: the remaining float-typed integer quantities
+
+0.2.1 converted the obvious counts, but a regex-driven sweep missed 19 more —
+`consumers`, per-node `fdUsed`/`socketsUsed`, `queues`/`connections`/`channels`
+object totals, connection `connectedAt`, slowlog `id`/`startTime`/`durationUs`, and
+Redis `totalCommands`. A live RabbitMQ broker reported `"consumers": 0.0`.
+
+These are integers now. Genuinely fractional values — `consumerUtilisation`,
+`opsPerSec`, `fragmentationRatio`, and the `*Rate` fields — are unchanged.
+
+## Live-verified: RabbitMQ
+
+The entire RabbitMQ command group had never been run against a live broker. It has
+now been exercised against **RabbitMQ 3.13.7**: `doctor`, every read
+(`overview`, `queues`, `queue`, `connections`, `channels`, `policies`, `nodes`) with
+queue depth cross-checked against `rabbitmqadmin` ground truth, the backlog and
+churn analyses, and the full governance loop — `set_policy` really created a policy
+on the broker, `priorState` recorded that it had not existed, and `undo_apply`
+deleted it, with all three calls audited.
+
+The platform guard was confirmed too: a Redis-only analysis against a RabbitMQ
+target fails with a teaching error naming the mismatch.
+
+See [docs/VERIFICATION.md](docs/VERIFICATION.md). Redis cluster/sentinel topologies
+and AUTH/TLS connections remain unverified.

queue_aiops-0.2.2/docs/VERIFICATION.md

@@ -0,0 +1,34 @@
+# Live verification status
+
+This document records what has and has not been validated against real Redis /
+RabbitMQ servers, so the maturity claim is auditable rather than a vibe.
+
+## Already live-verified ✅ — Redis 7.4.9, 2026-07-19
+
+Exercised end-to-end against a real **Redis 7.4.9** server (Docker) seeded with
+202 keys and a list-backed job queue:
+
+- `doctor` against a live server: PING OK, no-AUTH lab path reported clearly.
+- Every Redis read cross-checked against `redis-cli` ground truth:
+  `overview`, `redis info/memory/clients/slowlog/keyspace/bigkeys`
+  (key count matched `DBSIZE` exactly).
+- All four analyses ran clean: `analyze memory/latency/backlog/churn`.
+- Governance loop end-to-end: `redis_config_set` really changed
+  `maxmemory-policy`, captured `noeviction` as `priorState`, wrote an audit row
+  with approver, and `undo_apply` restored the prior value on the live server.
+
+**A real defect was found and fixed by this run**: integer quantities were
+rendered as floats — `202.0` keys, `1.0` connected clients, float byte counts —
+because they were routed through `num()`. Values were arithmetically right but
+semantically wrong, and equality assertions could not catch it
+(`202 == 202.0`). Fixed with `as_int()` across the Redis and RabbitMQ reads,
+plus a regression test that asserts the *type*, keeping genuine ratios
+(`hitRatePct`, `usedPctOfMax`, `opsPerSec`) as floats.
+
+## Not yet live-verified ⚠️
+
+- **RabbitMQ** — the entire `rabbitmq` command group and its management-API
+  shapes are unit-tested only. This is now the largest gap in this repo.
+- Redis **cluster / sentinel** topologies (only standalone was exercised).
+- AUTH-enabled Redis and TLS connections.
+- `kill-client` against a real blocked client.

{queue_aiops-0.2.0 → queue_aiops-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "queue-aiops"
-version = "0.2.0"
+version = "0.2.2"
 description = "Governed AI-ops for redis + rabbitmq: memory-pressure/latency/queue-backlog/connection-churn RCAs, slowlog and SCAN-budgeted big-key sampling, queues/policies/nodes, and governed writes (config set, client kill, purge/delete queue, policies) with a built-in governance harness (audit, budget, undo, risk tiers)"
 readme = "README.md"
 license = "MIT"

{queue_aiops-0.2.0 → queue_aiops-0.2.2}/queue_aiops/ops/_util.py

@@ -50,13 +50,36 @@ def pick(row: dict, *keys: str, default: Any = None) -> Any:
 
 
 def num(value: Any) -> float:
-    """Coerce a numeric cell to float; 0.0 when absent/non-numeric."""
+    """Coerce a numeric cell to float; 0.0 when absent/non-numeric.
+
+    Use this only for genuinely fractional values (rates, ratios, percentages).
+    For integer quantities — key counts, byte counts, client counts, whole
+    seconds — use :func:`as_int`, which keeps them integers.
+    """
     try:
         return float(value)
     except (TypeError, ValueError):
         return 0.0
 
 
+def as_int(value: Any) -> int:
+    """Coerce an integer quantity (counts, bytes, whole seconds) to ``int``.
+
+    Redis ``INFO`` and the RabbitMQ management API hand these back as strings;
+    routing them through :func:`num` rendered them as ``202.0`` keys or
+    ``1.0`` connected clients — arithmetically right but semantically wrong,
+    since a count cannot be fractional. A reader (human or model) should not
+    have to wonder whether a ``.0`` means the value was rounded.
+
+    Non-numeric/absent yields ``0`` to match :func:`num`'s contract for these
+    always-present INFO fields.
+    """
+    try:
+        return int(float(value))
+    except (TypeError, ValueError):
+        return 0
+
+
 def rate(row: Any, default: float = 0.0) -> float:
     """Read a management-API ``*_details.rate`` cell (``{"rate": 1.2}``)."""
     if isinstance(row, dict):

{queue_aiops-0.2.0 → queue_aiops-0.2.2}/queue_aiops/ops/rabbit_reads.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 
 from typing import Any
 
-from queue_aiops.ops._util import as_obj, num, opt, pick, rate, s
+from queue_aiops.ops._util import as_int, as_obj, num, opt, pick, rate, s
 
 MAX_ROWS = 200
 
@@ -28,13 +28,13 @@ def broker_overview(conn: Any) -> dict:
             "version": opt(pick(obj, "rabbitmq_version", "product_version")),
             "clusterName": opt(obj.get("cluster_name")),
             "node": opt(obj.get("node")),
-            "messagesReady": num(totals.get("messages_ready")),
-            "messagesUnacked": num(totals.get("messages_unacknowledged")),
-            "messagesTotal": num(totals.get("messages")),
-            "queues": num(objects.get("queues")),
-            "connections": num(objects.get("connections")),
-            "channels": num(objects.get("channels")),
-            "consumers": num(objects.get("consumers")),
+            "messagesReady": as_int(totals.get("messages_ready")),
+            "messagesUnacked": as_int(totals.get("messages_unacknowledged")),
+            "messagesTotal": as_int(totals.get("messages")),
+            "queues": as_int(objects.get("queues")),
+            "connections": as_int(objects.get("connections")),
+            "channels": as_int(objects.get("channels")),
+            "consumers": as_int(objects.get("consumers")),
             "publishRate": rate(stats.get("publish_details")),
             "deliverRate": rate(stats.get("deliver_get_details")),
             "ackRate": rate(stats.get("ack_details")),
@@ -56,11 +56,11 @@ def _queue_row(q: dict) -> dict:
         "vhost": opt(q.get("vhost"), 64),
         "state": opt(q.get("state"), 32),
         "durable": bool(q.get("durable")),
-        "messages": num(q.get("messages")),
-        "messagesReady": num(q.get("messages_ready")),
-        "messagesUnacked": num(q.get("messages_unacknowledged")),
-        "consumers": num(q.get("consumers")),
-        "memoryBytes": num(q.get("memory")),
+        "messages": as_int(q.get("messages")),
+        "messagesReady": as_int(q.get("messages_ready")),
+        "messagesUnacked": as_int(q.get("messages_unacknowledged")),
+        "consumers": as_int(q.get("consumers")),
+        "memoryBytes": as_int(q.get("memory")),
         "publishRate": rate(stats.get("publish_details")),
         "deliverRate": rate(stats.get("deliver_get_details")),
         "ackRate": rate(stats.get("ack_details")),
@@ -123,8 +123,8 @@ def list_connections(conn: Any) -> dict:
                 "peerHost": opt(pick(c, "peer_host", default="(unknown)"), 64),
                 "user": opt(c.get("user"), 64),
                 "state": opt(c.get("state"), 32),
-                "channels": num(c.get("channels")),
-                "connectedAt": num(c.get("connected_at")),
+                "channels": as_int(c.get("channels")),
+                "connectedAt": as_int(c.get("connected_at")),
                 "clientProduct": s(as_obj(c.get("client_properties")).get("product"), 64),
             }
             for c in conn.platform.rows(conn.get(conn.platform.path("connections")))
@@ -158,9 +158,9 @@ def list_channels(conn: Any) -> dict:
                 "connection": s(as_obj(c.get("connection_details")).get("name"), 128),
                 "user": opt(c.get("user"), 64),
                 "state": opt(c.get("state"), 32),
-                "unacked": num(c.get("messages_unacknowledged")),
-                "prefetch": num(c.get("prefetch_count")),
-                "consumers": num(c.get("consumer_count")),
+                "unacked": as_int(c.get("messages_unacknowledged")),
+                "prefetch": as_int(c.get("prefetch_count")),
+                "consumers": as_int(c.get("consumer_count")),
             }
             for c in conn.platform.rows(conn.get(conn.platform.path("channels")))
         ]
@@ -190,7 +190,7 @@ def list_policies(conn: Any, vhost: str | None = None) -> dict:
                 "vhost": opt(p.get("vhost"), 64),
                 "pattern": opt(p.get("pattern"), 128),
                 "applyTo": opt(pick(p, "apply-to", "apply_to", default="all"), 32),
-                "priority": num(p.get("priority")),
+                "priority": as_int(p.get("priority")),
                 "definition": as_obj(p.get("definition")),
             }
             for p in conn.platform.rows(conn.get(path))
@@ -220,13 +220,13 @@ def node_health(conn: Any) -> dict:
                     "memUsedBytes": mem_used,
                     "memLimitBytes": mem_limit,
                     "memAlarm": bool(n.get("mem_alarm")),
-                    "diskFreeBytes": num(n.get("disk_free")),
-                    "diskFreeLimitBytes": num(n.get("disk_free_limit")),
+                    "diskFreeBytes": as_int(n.get("disk_free")),
+                    "diskFreeLimitBytes": as_int(n.get("disk_free_limit")),
                     "diskAlarm": bool(n.get("disk_free_alarm")),
-                    "fdUsed": num(n.get("fd_used")),
-                    "fdTotal": num(n.get("fd_total")),
-                    "socketsUsed": num(n.get("sockets_used")),
-                    "socketsTotal": num(n.get("sockets_total")),
+                    "fdUsed": as_int(n.get("fd_used")),
+                    "fdTotal": as_int(n.get("fd_total")),
+                    "socketsUsed": as_int(n.get("sockets_used")),
+                    "socketsTotal": as_int(n.get("sockets_total")),
                 }
             )
         rows.sort(key=lambda r: r["memUsedBytes"], reverse=True)

{queue_aiops-0.2.0 → queue_aiops-0.2.2}/queue_aiops/ops/redis_reads.py

@@ -15,7 +15,7 @@ from __future__ import annotations
 
 from typing import Any
 
-from queue_aiops.ops._util import as_obj, num, opt, pct, s
+from queue_aiops.ops._util import as_int, as_obj, num, opt, pct, s
 
 # Hard bounds for the SCAN-based big-key sample (never KEYS *).
 SCAN_BUDGET_KEYS = 10_000  # max keys walked per call
@@ -35,14 +35,14 @@ def server_info(conn: Any) -> dict:
             "platform": conn.target.platform,
             "version": opt(info.get("redis_version")),
             "mode": opt(info.get("redis_mode")),
-            "uptimeSeconds": num(info.get("uptime_in_seconds")),
+            "uptimeSeconds": as_int(info.get("uptime_in_seconds")),
             "role": opt(info.get("role")),
-            "connectedClients": num(info.get("connected_clients")),
-            "blockedClients": num(info.get("blocked_clients")),
+            "connectedClients": as_int(info.get("connected_clients")),
+            "blockedClients": as_int(info.get("blocked_clients")),
             "opsPerSec": num(info.get("instantaneous_ops_per_sec")),
-            "totalCommands": num(info.get("total_commands_processed")),
-            "keyspaceHits": num(info.get("keyspace_hits")),
-            "keyspaceMisses": num(info.get("keyspace_misses")),
+            "totalCommands": as_int(info.get("total_commands_processed")),
+            "keyspaceHits": as_int(info.get("keyspace_hits")),
+            "keyspaceMisses": as_int(info.get("keyspace_misses")),
             "hitRatePct": pct(
                 num(info.get("keyspace_hits")),
                 num(info.get("keyspace_hits")) + num(info.get("keyspace_misses")),
@@ -56,8 +56,8 @@ def memory_stats(conn: Any) -> dict:
     """[READ] Memory posture: used vs maxmemory, policy, fragmentation, peaks."""
     try:
         info = as_obj(conn.redis_info("memory"))
-        used = num(info.get("used_memory"))
-        maxmem = num(info.get("maxmemory"))
+        used = as_int(info.get("used_memory"))
+        maxmem = as_int(info.get("maxmemory"))
         stats = as_obj(conn.redis_memory_stats())
         return {
             "usedBytes": used,
@@ -66,11 +66,11 @@ def memory_stats(conn: Any) -> dict:
             "usedPctOfMax": pct(used, maxmem),
             "maxmemoryPolicy": opt(info.get("maxmemory_policy")),
             "fragmentationRatio": num(info.get("mem_fragmentation_ratio")),
-            "rssBytes": num(info.get("used_memory_rss")),
-            "peakBytes": num(info.get("used_memory_peak")),
-            "keysCount": num(stats.get("keys.count")),
-            "overheadBytes": num(stats.get("overhead.total")),
-            "datasetBytes": num(stats.get("dataset.bytes")),
+            "rssBytes": as_int(info.get("used_memory_rss")),
+            "peakBytes": as_int(info.get("used_memory_peak")),
+            "keysCount": as_int(stats.get("keys.count")),
+            "overheadBytes": as_int(stats.get("overhead.total")),
+            "datasetBytes": as_int(stats.get("dataset.bytes")),
         }
     except Exception as exc:  # noqa: BLE001 — report as partial
         return {"error": s(exc, 200)}
@@ -85,8 +85,8 @@ def list_clients(conn: Any) -> dict:
                 "id": opt(c.get("id"), 32),
                 "addr": opt(c.get("addr"), 64),
                 "name": opt(c.get("name"), 64),
-                "ageSeconds": num(c.get("age")),
-                "idleSeconds": num(c.get("idle")),
+                "ageSeconds": as_int(c.get("age")),
+                "idleSeconds": as_int(c.get("idle")),
                 "lastCommand": opt(c.get("cmd"), 64),
                 "db": opt(c.get("db"), 8),
                 "flags": opt(c.get("flags"), 16),
@@ -143,9 +143,9 @@ def slowlog(conn: Any, count: int = MAX_SLOWLOG_ROWS) -> dict:
         entries = conn.redis_slowlog(want + 1)
         rows = [
             {
-                "id": num(e.get("id")),
-                "startTime": num(e.get("start_time")),
-                "durationUs": num(e.get("duration")),
+                "id": as_int(e.get("id")),
+                "startTime": as_int(e.get("start_time")),
+                "durationUs": as_int(e.get("duration")),
                 "command": _command_text(e.get("command")),
                 "clientAddr": opt(e.get("client_address"), 64),
                 "clientName": opt(e.get("client_name"), 64),
@@ -183,15 +183,15 @@ def keyspace(conn: Any) -> dict:
         dbs = []
         for name, cell in info.items():
             cell = as_obj(cell) if isinstance(cell, dict) else _parse_keyspace_cell(cell)
-            keys = num(cell.get("keys"))
-            expires = num(cell.get("expires"))
+            keys = as_int(cell.get("keys"))
+            expires = as_int(cell.get("expires"))
             dbs.append(
                 {
                     "db": s(name, 16),
                     "keys": keys,
                     "expires": expires,
                     "expiresPct": pct(expires, keys),
-                    "avgTtlMs": num(cell.get("avg_ttl")),
+                    "avgTtlMs": as_int(cell.get("avg_ttl")),
                 }
             )
         return {"databases": dbs, "totalKeys": sum(d["keys"] for d in dbs)}
@@ -235,7 +235,7 @@ def big_key_sample(conn: Any, top: int = TOP_KEYS) -> dict:
         for key in sampled:
             usage = conn.redis_memory_usage(key)
             if usage is not None:
-                sized.append({"key": s(key, 128), "bytes": float(usage)})
+                sized.append({"key": s(key, 128), "bytes": int(usage)})
         sized.sort(key=lambda e: e["bytes"], reverse=True)
 
         return {

{queue_aiops-0.2.0 → queue_aiops-0.2.2}/server.json

@@ -7,12 +7,12 @@
     "url": "https://github.com/AIops-tools/Queue-AIops",
     "source": "github"
   },
-  "version": "0.2.0",
+  "version": "0.2.2",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "queue-aiops",
-      "version": "0.2.0",
+      "version": "0.2.2",
       "transport": {
         "type": "stdio"
       }

{queue_aiops-0.2.0 → queue_aiops-0.2.2}/tests/test_reads.py

@@ -97,6 +97,36 @@ def test_keyspace_parses_raw_cells():
     assert out["databases"][0]["expiresPct"] == 40.0
 
 
+@pytest.mark.unit
+def test_integer_quantities_are_ints_not_floats():
+    """Counts and byte totals must be int; only ratios stay float.
+
+    Regression from live verification against Redis 7.4: INFO values routed
+    through ``num()`` rendered as ``202.0`` keys and ``1.0`` clients. Equality
+    assertions cannot catch this (``202 == 202.0``), so assert the *type*.
+    """
+    conn = redis_conn(
+        info={
+            "keyspace": {"db0": "keys=100,expires=40,avg_ttl=5000"},
+            "memory": {"used_memory": "1374096", "maxmemory": "0"},
+            "clients": {"connected_clients": "1", "blocked_clients": "0"},
+            "server": {"uptime_in_seconds": "1790"},
+            "stats": {"keyspace_hits": "7", "keyspace_misses": "0"},
+        }
+    )
+    ks = redis_reads.keyspace(conn)
+    assert isinstance(ks["totalKeys"], int)
+    assert isinstance(ks["databases"][0]["keys"], int)
+    assert isinstance(ks["databases"][0]["expires"], int)
+    # …but a genuine ratio must stay float.
+    assert isinstance(ks["databases"][0]["expiresPct"], float)
+
+    mem = redis_reads.memory_stats(conn)
+    assert isinstance(mem["usedBytes"], int)
+    assert isinstance(mem["maxmemoryBytes"], int)
+    assert isinstance(mem["usedPctOfMax"], float)
+
+
 @pytest.mark.unit
 def test_big_key_sample_scans_and_sizes_topmost():
     conn = redis_conn(
@@ -107,7 +137,7 @@ def test_big_key_sample_scans_and_sizes_topmost():
     out = redis_reads.big_key_sample(conn)
     assert out["scannedKeys"] == 3
     assert out["coveragePct"] == 100.0
-    assert out["topKeys"][0] == {"key": "k2", "bytes": 50_000_000.0}
+    assert out["topKeys"][0] == {"key": "k2", "bytes": 50_000_000}
 
 
 @pytest.mark.unit

{queue_aiops-0.2.0 → queue_aiops-0.2.2}/uv.lock

@@ -781,7 +781,7 @@ wheels = [
 
 [[package]]
 name = "queue-aiops"
-version = "0.2.0"
+version = "0.2.2"
 source = { editable = "." }
 dependencies = [
     { name = "cryptography" },

queue_aiops-0.2.0/RELEASE_NOTES.md

@@ -1,48 +0,0 @@
-# Release notes — queue-aiops 0.2.0
-
-Previous release: 0.1.1.
-
-## Headline: read-only mode
-
-```bash
-export QUEUE_READ_ONLY=1
-```
-
-With this set the **8 write tools are never registered** — an MCP
-client lists **20 tools instead of 28**. The writes are not hidden
-behind a flag and not merely refused on call: they are absent from the session,
-so a model cannot invoke one and cannot be argued into one. For a reviewer this
-is checkable rather than promised — connect, list the tools, and the writes are
-not there.
-
-Enforcement is two layers deep: the `@governed_tool` harness refuses every
-non-read operation (covering the CLI and in-process callers too), and the MCP
-server removes write tools from `list_tools()`. Changing entry point does not
-get around it.
-
-## BREAKING — return shapes changed
-
-This release changes payloads that callers may be parsing. Both changes exist
-to stop a result from misrepresenting itself:
-
-1. **Absent fields are now `null`, not `""`.** A missing value and an empty value
-   were previously indistinguishable, which invited consumers to invent the
-   difference. Keys are still always present — only the value may be null.
-2. **Anything with a `limit` now returns an envelope** —
-   `{"<items>": [...], "returned": N, "limit": L, "truncated": bool}`. Truncation is
-   *measured* (one extra row is fetched), never inferred from the page happening to
-   be full. Where a genuine pre-cap total is knowable it is reported as `total`;
-   where it isn't, `total` is deliberately omitted rather than echoing `returned`.
-
-## Also in this release
-
-- **`docs/VERIFICATION.md`** — what the mock suite actually guarantees, a live
-  verification checklist, and the criteria for claiming this tool verified.
-- **`skills/queue-aiops/references/agent-guardrails.md`** — for driving this tool with a
-  smaller / local model: which guardrails are now enforced for you, and a
-  ready-made system prompt for the rest.
-- Expanded operator playbooks in the skill documentation.
-- The advertised tool count now matches what an MCP client actually lists
-  (it includes `undo_list` / `undo_apply`), and a release gate keeps it honest.
-- The `(preview)` label has been dropped. It never meant unreleased; verification
-  status now lives in `docs/VERIFICATION.md` where it can be specific.

queue_aiops-0.2.0/docs/VERIFICATION.md

@@ -1,200 +0,0 @@
-# Live verification — redis / rabbitmq
-
-`queue-aiops` is exercised by a **mock-only** test suite (`uv run pytest`, no real
-broker). It has **not** yet been validated end-to-end against a live redis instance or
-rabbitmq broker. This document says exactly what the mock suite already guarantees, and
-what a live run has to prove before anyone may describe this tool as verified against a
-real broker.
-
-It is deliberately checklist-shaped so the result is reproducible and auditable — not a
-subjective "seems fine".
-
-## What the mock suite already guarantees
-
-- Every module imports; the CLI builds; **all 28 MCP tools** carry the `@governed_tool`
-  harness marker (`tests/test_smoke.py`, which also asserts the tool count and that
-  `__version__` matches `pyproject.toml`).
-- The four flagship analyses (`redis_memory_pressure_rca`, `redis_latency_rca`,
-  `rabbitmq_queue_backlog_rca`, `connection_churn_analysis`) are unit-tested against
-  synthetic telemetry: each cause classification fires on the right signal
-  (noeviction-near-limit vs active eviction vs fragmentation vs swapping; O(N) command
-  patterns and fork/AOF stalls; no-consumers vs unacked pile-up vs rate deficit),
-  findings cite the measured number, and partial/missing fields do not crash.
-- The **platform registry** resolves each tool to the correct redis (RESP, via the
-  `redis` Python client) or rabbitmq (management HTTP API, HTTP Basic) shape.
-- **Safety invariants** are tested: the redis surface is a typed command **allow-list**
-  with no generic passthrough; big-key sampling is `SCAN`-based under a hard budget and
-  **never** issues `KEYS *`; and rabbitmq path segments (queue/policy names, and the
-  default vhost `/` → `%2F`) are percent-encoded centrally.
-- Reversible writes record a faithful **inverse** undo descriptor built from a fetched
-  before-state (`redis_config_set` restores the prior value from `CONFIG GET`;
-  `set_policy` / `delete_policy` restore the captured definition; `declare_queue`'s undo
-  deletes it only when newly created). `purge_queue` declares **no** undo;
-  `delete_queue`'s undo re-declares the captured definition and the tests assert that
-  **messages are not claimed to be restored**.
-- Governance persistence is tested against a real on-disk SQLite audit DB: calls land as
-  rows, failures record `status=error` and no undo, and the secure-by-default approver
-  gate refuses high-risk ops when no `rules.yaml` exists.
-
-What it does **not** guarantee: that the concrete `INFO` field names, `SLOWLOG` entry
-shape, and rabbitmq management-API JSON match a real broker build. Those are modelled
-from each project's public documentation and are the **largest verification debt in this
-repo** — `INFO` field names in particular have shifted across redis 5/6/7.
-
-## Prerequisites for a live run
-
-Both platforms are free and trivially containerised:
-
-```bash
-docker run -d --name redis-verify -p 6379:6379 redis:7 \
-  redis-server --maxmemory 128mb --maxmemory-policy noeviction
-docker run -d --name rabbit-verify -p 5672:5672 -p 15672:15672 rabbitmq:3-management
-```
-
-The rabbitmq **management plugin** must be enabled (the `-management` image does this),
-and the API user needs the `monitoring` or `management` tag.
-
-Use a **throwaway broker with throwaway data**. The checklist purges and deletes queues,
-kills clients, and changes the running config — `purge_queue` destroys real messages and
-records **no undo**. Never point it at a broker carrying traffic you care about.
-
-Set the lab up so the reads have something to find:
-
-- Fill redis past 80% of a small `maxmemory` and leave the policy at `noeviction`, so the
-  most dangerous finding is reachable.
-- Create a few deliberately oversized keys (a large hash and a large list).
-- Run some `KEYS`/`SMEMBERS` calls so the SLOWLOG has genuine O(N) entries.
-- On rabbitmq, create three queues: one with **no consumer** and messages published, one
-  with a consumer that **never acks**, and one healthy — the three backlog causes.
-
-```bash
-uv tool install queue-aiops
-queue-aiops init      # wizard: pick platform, optional encrypted secret
-```
-
-Record the exact versions tested (e.g. "redis 7.4, rabbitmq 3.13") — a tick is only
-meaningful with the build it was ticked against.
-
-## Verification checklist
-
-Tick every box, **per platform**. A box that cannot be ticked is a verification gap —
-record it, do not silently pass.
-
-### 1. Connectivity (the fastest live gate)
-- [ ] `queue-aiops doctor` → green on each target: config parsed, secret store unlocks,
-      and a real `PING` / `/api/overview` returns.
-- [ ] `queue-aiops doctor --skip-auth` → passes offline (config/secret checks only).
-- [ ] An **auth-less** lab redis connects with no stored secret (this is a supported
-      configuration and a common mock-vs-reality divergence).
-- [ ] One config spanning both platforms works with `--target` switching.
-
-### 2. Reads return real, well-shaped data
-- [ ] `queue-aiops overview` → real version/role, memory posture, client counts, ops/sec,
-      hit rate and key count (redis); version, queue/message totals, connection/channel/
-      consumer counts and node alarms (rabbitmq). Confirm a **partial** failure degrades
-      into the `errors` list rather than failing the whole call.
-- [ ] `queue-aiops redis info` / `redis memory` → fields match `redis-cli INFO`
-      **on each of redis 6 and 7**, since field names have moved between versions.
-- [ ] `queue-aiops redis clients` → matches `CLIENT LIST`; `redis keyspace` matches
-      `DBSIZE` per database.
-- [ ] `queue-aiops redis slowlog --limit 50` → matches `SLOWLOG GET`, with timings
-      parsed correctly.
-- [ ] `queue-aiops redis config-get maxmemory*` → glob patterns work and match
-      `CONFIG GET`.
-- [ ] `queue-aiops redis bigkeys --count 500` → finds the oversized keys you planted, and
-      reports a **coverage %** consistent with the keyspace size. Confirm with
-      `MONITOR` or the slowlog that it issued `SCAN`, **never** `KEYS *` — this is the
-      single most important safety check in the file.
-- [ ] `queue-aiops rabbitmq queues` / `queue <name>` / `connections` / `channels` /
-      `policies` / `nodes` → match the management UI, including ready-vs-unacked splits.
-- [ ] A queue and a policy whose **names need percent-encoding** (a `/`, a space, a `%`)
-      are read correctly, and the default vhost `/` resolves as `%2F`.
-
-### 3. The analyses are right, not just non-crashing
-- [ ] With redis near `maxmemory` under `noeviction`,
-      `queue-aiops analyze memory --used-pct 85` raises the **noeviction-near-limit**
-      finding and cites the real used/max numbers. Switch to `allkeys-lru`, drive
-      evictions, and confirm the finding changes to active eviction.
-- [ ] Fragmentation vs swapping are distinguished correctly (do not accept "flagged
-      something" — check it names the right one).
-- [ ] `queue-aiops analyze latency --slow-us 10000` digests the planted O(N) entries by
-      **command pattern** and suggests the incremental variant (`KEYS` → `SCAN`).
-- [ ] Trigger a background save on a large dataset; the fork/AOF stall signal appears.
-- [ ] `queue-aiops analyze backlog --top 20` classifies each of your three planted
-      queues correctly: **no consumers**, **unacked pile-up**, and healthy.
-- [ ] Drive the node past its memory watermark; the alarm is reported as blocking **all**
-      publishers, and outranks the per-queue findings.
-- [ ] `queue-aiops analyze churn` on both platforms pins reconnect churn to the right
-      client source.
-
-### 4. A reversible write + its undo (governance closes the loop)
-- [ ] `queue-aiops redis config-set maxmemory-policy allkeys-lru --dry-run` → prints the
-      call, `CONFIG GET` shows the value unchanged.
-- [ ] `queue-aiops redis config-set maxmemory-policy allkeys-lru` → the running config
-      changes, the result carries an `_undo_id`, and a row lands in
-      `~/.queue-aiops/audit.db`.
-- [ ] `queue-aiops undo list` shows it; `undo apply <id>` restores the **prior** policy —
-      verify starting from a non-default value, where a naive undo would wrongly set
-      `noeviction`.
-- [ ] `queue-aiops rabbitmq set-policy <name> <pattern> '{"max-length":1000}'` over an
-      **existing** policy, then `undo apply` → the prior definition returns intact (not
-      a deletion).
-- [ ] `queue-aiops rabbitmq declare-queue <new> --dry-run` then for real, then
-      `undo apply` → the newly created queue is deleted. Repeat against a queue that
-      **already existed**: the undo must **not** delete it.
-
-### 5. Irreversible / asymmetric writes behave as declared
-- [ ] `queue-aiops rabbitmq purge <queue> --dry-run` → reports the message count about to
-      be destroyed; the real run destroys exactly that many and records **no** undo.
-- [ ] `queue-aiops rabbitmq delete-queue <queue>` on a queue **with messages**, then
-      `undo apply` → the queue is re-declared with the right durable/auto-delete flags,
-      and the **messages are gone**. Confirm the tool never claimed otherwise.
-- [ ] `queue-aiops redis kill-client --addr <ip:port>` drops that connection, records no
-      undo, and is audited.
-
-### 6. Governance actually gates
-- [ ] With no `~/.queue-aiops/rules.yaml`, `purge_queue` and `delete_queue` are
-      **refused** unless `QUEUE_AUDIT_APPROVED_BY` is set (secure-by-default); with it
-      plus `QUEUE_AUDIT_RATIONALE`, both appear in the audit row.
-- [ ] A tight poll loop trips the runaway budget guard rather than hammering the broker.
-- [ ] A failed call (nonexistent queue) is audited `status=error` and records no undo.
-- [ ] Attempting a redis command outside the typed allow-list is rejected **before** the
-      client sends anything — confirm against the live server that nothing executes.
-
-### 7. Cleanup
-- [ ] Restore every config value you changed, delete the throwaway queues and policies,
-      and flush the lab redis.
-- [ ] `queue-aiops overview` matches the baseline you captured before starting.
-- [ ] Skim `~/.queue-aiops/audit.db` — every write is there with the right risk tier.
-
-## Criteria to consider it live-verified
-
-All of the following must hold:
-
-1. Every box above is ticked against **both** a real redis and a real rabbitmq, with the
-   exact builds recorded (e.g. "redis 7.4 + rabbitmq 3.13"), and the redis reads
-   re-checked on at least **two major redis versions** given the `INFO` field drift.
-2. Every field-name or API-shape mismatch found is **fixed and covered by a regression
-   test**, so the mock suite would now catch it.
-3. Section 4 passed, including the asymmetric `declare_queue` case (undo must delete only
-   a queue it created). Recording an undo descriptor is not the same as the undo
-   working, and this product line has shipped broken undo pairs before.
-4. The big-key sampler was confirmed **live** to issue `SCAN` under budget and never
-   `KEYS *` — a mock cannot prove this, and getting it wrong stalls a production redis.
-5. The run is written up in the release notes / product-line memory with the date and
-   package version, matching how the line records its other live-verified tools.
-
-Until then, this repo says only what is true: mock-validated, live-unverified. Claiming
-otherwise would break that promise.
-
-## Notes for maintainers
-
-- `queue-aiops doctor` is the single fastest live entry point; start there.
-- Weight the run toward **redis `INFO` field names** and **rabbitmq percent-encoded path
-  segments** — those are the two places the mocks are least able to model.
-- Managed cloud queue services (ElastiCache, Amazon MQ, CloudAMQP, …) are a **separate**
-  verification target: wire-compatible reads may work, but `CONFIG SET` and
-  `CLIENT KILL` are commonly restricted. Do not infer managed support from a self-hosted
-  run.
-- Add this tool's result to the product-line verification ledger once green, so the
-  central "verification debt" list stays accurate.