postgres-aiops 0.10.2__tar.gz → 0.11.0__tar.gz

{postgres_aiops-0.10.2 → postgres_aiops-0.11.0}/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "postgres-aiops",
   "displayName": "Postgres AIops",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "description": "Governed PostgreSQL DBA ops: slow-query RCA, bloat/vacuum & blocking-lock analysis; 35 MCP tools.",
   "author": {
     "name": "Wei Zhou",

{postgres_aiops-0.10.2 → postgres_aiops-0.11.0}/.mcp.json

@@ -5,7 +5,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "postgres-aiops==0.10.2",
+        "postgres-aiops==0.11.0",
         "postgres-aiops-mcp"
       ]
     }

{postgres_aiops-0.10.2 → postgres_aiops-0.11.0}/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## v0.11.0 — 2026-10-15
+
+### Added
+- MCP tool annotations derived from each tool's governance `risk_level`, so
+  clients can gate approval from `tools/list` alone. `low` tools advertise
+  `readOnlyHint: true`; every other tool advertises `readOnlyHint: false` and
+  `destructiveHint: true`. The `medium` tier includes deletes and hard
+  power-offs, so a tool is never advertised as non-destructive on the strength
+  of its tier. `idempotentHint` only repeats an explicit declaration. The exact
+  level is published in `_meta` under `io.github.AIops-tools/riskLevel`. These
+  are hints for the client; audit and undo are unchanged.
+
+### Fixed
+- `blocking_lock_chain_rca`: the chain root's state was dropped and a missing
+  query became `""`. For a backend that is `idle in transaction`, `rootQuery` is
+  the last statement it ran, not a running one, so the recommended
+  `cancel_query` had nothing to cancel. Roots now carry `rootState` and
+  `rootIdle` (true for any `idle*` state, including plain `idle` with session-level locks), a missing query stays `null`, and the action for an
+  idle root points at `terminate_backend` (which rolls the transaction back).
+
+## v0.10.3 — 2026-09-15
+
+### Fixed
+- CLI commands that read the engine without calling an MCP tool now write an
+  audit row, as every MCP call does: they run through the same `@governed_tool`
+  harness, budget and runaway guard included. Before, an operator's CLI reads
+  left no trace in `audit.db`, contrary to the documented guarantee that MCP
+  and CLI are audited alike. A test fails if any engine command escapes it.
+
 ## v0.10.2 — 2026-09-12
 
 ### Changed

{postgres_aiops-0.10.2 → postgres_aiops-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: postgres-aiops
-Version: 0.10.2
+Version: 0.11.0
 Summary: Governed AI-ops for PostgreSQL DBA operations: slow-query RCA, bloat/vacuum & blocking-lock analysis with a built-in governance harness (audit, budget, undo, risk tiers)
 Author-email: Wei Zhou <zhouwei008@gmail.com>
 License-Expression: MIT

{postgres_aiops-0.10.2 → postgres_aiops-0.11.0}/RELEASE_NOTES.md

@@ -1,5 +1,8 @@
 # Release notes — postgres-aiops 0.6.0
 
+> Historical — this file covers the 0.6.0 release only and is not updated.
+> For every release since, see [CHANGELOG.md](CHANGELOG.md) and the GitHub releases.
+
 Previous release: 0.5.0.
 
 ## BREAKING — the authorization layer is removed

postgres_aiops-0.11.0/mcp_server/_annotations.py

@@ -0,0 +1,66 @@
+"""Derive MCP tool annotations from the governance risk level.
+
+Every tool already declares ``risk_level`` on ``@governed_tool``; this module
+publishes it to MCP clients as the standard ``ToolAnnotations`` hints plus the
+exact level under ``_meta``, so a client can gate approval without reading our
+docstrings.
+
+Only the safe direction is ever asserted:
+
+- ``low`` → ``readOnlyHint: true``. Backed by the smoke-test invariant that
+  ``risk_level == "low"`` exactly when the docstring says ``[READ]``.
+- anything else → ``readOnlyHint: false, destructiveHint: true``. The
+  ``medium`` tier is NOT non-destructive — it holds deletes, hard power-offs,
+  state kills and stat resets — so claiming ``destructiveHint: false`` from the
+  tier would tell a client it may skip approval for a delete. Over-warning
+  costs a confirmation prompt; under-warning costs data.
+- ``idempotentHint`` only echoes an explicit ``@governed_tool(idempotent=True)``
+  declaration; it is never inferred.
+- ``openWorldHint`` is left unset (spec default ``true``): every tool talks to
+  an external system.
+
+This file is identical across the AIops line; keep it that way.
+"""
+
+from typing import Any
+
+from mcp.types import ToolAnnotations
+
+RISK_META_KEY = "io.github.AIops-tools/riskLevel"
+RISK_LEVELS = frozenset({"low", "medium", "high", "critical"})
+
+
+def annotations_for(risk_level: str, idempotent: bool) -> ToolAnnotations:
+    """Return the MCP hints that a tool of ``risk_level`` may honestly claim."""
+    if risk_level not in RISK_LEVELS:
+        raise ValueError(
+            f"unknown risk_level {risk_level!r}; expected one of {sorted(RISK_LEVELS)}"
+        )
+    if risk_level == "low":
+        return ToolAnnotations(read_only_hint=True)
+    return ToolAnnotations(
+        read_only_hint=False,
+        destructive_hint=True,
+        idempotent_hint=idempotent,
+    )
+
+
+def apply_risk_annotations(server: Any) -> None:
+    """Replace every registered tool with a copy carrying its risk annotations.
+
+    Fails fast on a tool without ``@governed_tool`` metadata: an unannotated
+    tool would be advertised with the spec defaults, i.e. as a destructive
+    write with no stated risk level — wrong for a read, silent for a write.
+    """
+    tools = server._tool_manager._tools  # same private registry undo.py relies on
+    for name, tool in list(tools.items()):
+        risk_level = getattr(tool.fn, "_risk_level", None)
+        if risk_level is None:
+            raise RuntimeError(f"tool {name!r} has no @governed_tool risk_level")
+        idempotent = bool(getattr(tool.fn, "_idempotent", False))
+        tools[name] = tool.model_copy(
+            update={
+                "annotations": annotations_for(risk_level, idempotent),
+                "meta": {**(tool.meta or {}), RISK_META_KEY: risk_level},
+            }
+        )

{postgres_aiops-0.10.2 → postgres_aiops-0.11.0}/mcp_server/server.py

@@ -14,6 +14,7 @@ License: MIT
 import logging
 import os
 
+from mcp_server._annotations import apply_risk_annotations
 from mcp_server._shared import _safe_error, mcp, tool_errors
 
 # Importing the tool modules registers every @mcp.tool() onto the shared
@@ -30,6 +31,10 @@ from mcp_server.tools import (  # noqa: F401 — side effects
     undo,
 )
 
+# Publish each tool's governance risk level as MCP annotations. Runs after
+# every tool module has registered, so no tool is advertised unannotated.
+apply_risk_annotations(mcp)
+
 __all__ = ["mcp", "main", "_safe_error", "tool_errors"]
 
 logger = logging.getLogger(__name__)

{postgres_aiops-0.10.2 → postgres_aiops-0.11.0}/openclaw.plugin.json

@@ -11,7 +11,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "postgres-aiops==0.10.2",
+        "postgres-aiops==0.11.0",
         "postgres-aiops-mcp"
       ]
     }

{postgres_aiops-0.10.2 → postgres_aiops-0.11.0}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zw008/postgres-aiops",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "description": "Governed PostgreSQL DBA ops: slow-query RCA, bloat/vacuum & blocking-lock analysis; 35 MCP tools.",
   "private": true,
   "license": "MIT",

{postgres_aiops-0.10.2 → postgres_aiops-0.11.0}/postgres_aiops/cli/_common.py

@@ -180,3 +180,43 @@ def double_confirm(action: str, resource: str) -> None:
         f"Confirm 2/2: really {action} '{resource}'? This may be irreversible.",
         abort=True,
     )
+
+
+def audited(fn: Callable) -> Callable:
+    """Audit a CLI command that reaches the engine without calling an MCP tool.
+
+    MCP tools write their audit row through ``@governed_tool``; a CLI command that
+    called the ops layer directly used to write none, so an operator's CLI reads
+    left no trail. This runs the command through the same harness: one audit row per
+    invocation (tool = the command function, params = its options), plus the budget
+    and runaway guard. ``typer.Exit`` is how a command ends: exit code 0 is audited
+    ``ok``, a non-zero code ``error``, and the exit is re-raised unchanged. Any other
+    exception is audited ``error`` and propagates to ``cli_errors`` as before.
+    """
+    import functools as _functools
+
+    from postgres_aiops.governance import governed_tool
+
+    @_functools.wraps(fn)
+    def body(*args: Any, **kwargs: Any) -> Any:
+        try:
+            fn(*args, **kwargs)
+        except typer.Exit as exc:
+            code = exc.exit_code
+            outcome: dict[str, Any] = {"_exitCode": code}
+            if code:
+                outcome["error"] = f"command exited with code {code}"
+            return outcome
+        return None
+
+    governed = governed_tool(risk_level="low")(body)
+
+    @_functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        result = governed(*args, **kwargs)
+        if isinstance(result, dict) and "_exitCode" in result:
+            raise typer.Exit(result["_exitCode"])
+        return None
+
+    wrapper._is_audited_cli = True  # type: ignore[attr-defined]
+    return wrapper

{postgres_aiops-0.10.2 → postgres_aiops-0.11.0}/postgres_aiops/cli/activity.py

@@ -7,7 +7,7 @@ from typing import Annotated
 
 import typer
 
-from postgres_aiops.cli._common import TargetOption, cli_errors, console, get_connection
+from postgres_aiops.cli._common import TargetOption, audited, cli_errors, console, get_connection
 
 activity_app = typer.Typer(
     name="activity",
@@ -18,6 +18,7 @@ activity_app = typer.Typer(
 
 @activity_app.command("list")
 @cli_errors
+@audited
 def activity_list(
     state: Annotated[str | None, typer.Option("--state", help="Filter by state")] = None,
     target: TargetOption = None,
@@ -31,6 +32,7 @@ def activity_list(
 
 @activity_app.command("long")
 @cli_errors
+@audited
 def activity_long(
     min_seconds: Annotated[int, typer.Option("--min-seconds", help="Minimum age")] = 60,
     target: TargetOption = None,
@@ -44,6 +46,7 @@ def activity_long(
 
 @activity_app.command("locks")
 @cli_errors
+@audited
 def activity_locks(target: TargetOption = None) -> None:
     """List held/awaited locks."""
     from postgres_aiops.ops import activity as ops

{postgres_aiops-0.10.2 → postgres_aiops-0.11.0}/postgres_aiops/cli/analyze.py

@@ -8,6 +8,7 @@ import typer
 
 from postgres_aiops.cli._common import (
     TargetOption,
+    audited,
     cli_errors,
     get_connection,
     print_result,
@@ -22,6 +23,7 @@ analyze_app = typer.Typer(
 
 @analyze_app.command("slow-query")
 @cli_errors
+@audited
 def analyze_slow_query(
     explain_sql: Annotated[str | None, typer.Option("--explain", help="SQL to EXPLAIN")] = None,
     limit: Annotated[int, typer.Option("--limit", help="Statements to consider")] = 20,
@@ -41,6 +43,7 @@ def analyze_slow_query(
 
 @analyze_app.command("bloat-vacuum")
 @cli_errors
+@audited
 def analyze_bloat_vacuum(
     limit: Annotated[int, typer.Option("--limit", help="Tables to consider")] = 50,
     target: TargetOption = None,
@@ -58,6 +61,7 @@ def analyze_bloat_vacuum(
 
 @analyze_app.command("blocking")
 @cli_errors
+@audited
 def analyze_blocking(target: TargetOption = None) -> None:
     """Build the blocking-lock chain and name the root blocker."""
     from postgres_aiops.ops import activity, analysis

{postgres_aiops-0.10.2 → postgres_aiops-0.11.0}/postgres_aiops/cli/index.py

@@ -9,6 +9,7 @@ import typer
 
 from postgres_aiops.cli._common import (
     TargetOption,
+    audited,
     cli_errors,
     console,
     get_connection,
@@ -24,6 +25,7 @@ index_app = typer.Typer(
 
 @index_app.command("unused")
 @cli_errors
+@audited
 def index_unused(target: TargetOption = None) -> None:
     """Non-unique, non-primary indexes with zero scans."""
     from postgres_aiops.ops import indexes as ops
@@ -34,6 +36,7 @@ def index_unused(target: TargetOption = None) -> None:
 
 @index_app.command("missing")
 @cli_errors
+@audited
 def index_missing(target: TargetOption = None) -> None:
     """Tables with heavy sequential scans (missing-index hints)."""
     from postgres_aiops.ops import indexes as ops
@@ -44,6 +47,7 @@ def index_missing(target: TargetOption = None) -> None:
 
 @index_app.command("bloat")
 @cli_errors
+@audited
 def index_bloat(
     limit: Annotated[int, typer.Option("--limit", help="Indexes to inspect")] = 50,
     target: TargetOption = None,
@@ -57,6 +61,7 @@ def index_bloat(
 
 @index_app.command("invalid")
 @cli_errors
+@audited
 def index_invalid(target: TargetOption = None) -> None:
     """Invalid and duplicate indexes."""
     from postgres_aiops.ops import indexes as ops

{postgres_aiops-0.10.2 → postgres_aiops-0.11.0}/postgres_aiops/cli/overview.py

@@ -4,10 +4,11 @@ from __future__ import annotations
 
 import json
 
-from postgres_aiops.cli._common import TargetOption, cli_errors, console, get_connection
+from postgres_aiops.cli._common import TargetOption, audited, cli_errors, console, get_connection
 
 
 @cli_errors
+@audited
 def overview_cmd(target: TargetOption = None) -> None:
     """One-shot cluster health: version, connections, long queries, bloat, replication."""
     from postgres_aiops.ops import overview as ops

{postgres_aiops-0.10.2 → postgres_aiops-0.11.0}/postgres_aiops/cli/query.py

@@ -10,6 +10,7 @@ import typer
 from postgres_aiops.cli._common import (
     DryRunOption,
     TargetOption,
+    audited,
     checked,
     cli_errors,
     console,
@@ -28,6 +29,7 @@ query_app = typer.Typer(
 
 @query_app.command("top")
 @cli_errors
+@audited
 def query_top(
     order_by: Annotated[
         str, typer.Option("--order-by", help="total_time|mean_time|calls|rows|io")
@@ -44,6 +46,7 @@ def query_top(
 
 @query_app.command("explain")
 @cli_errors
+@audited
 def query_explain(
     sql: Annotated[str, typer.Argument(help="A single SQL statement to EXPLAIN")],
     analyze: Annotated[

{postgres_aiops-0.10.2 → postgres_aiops-0.11.0}/postgres_aiops/cli/replication.py

@@ -6,7 +6,7 @@ import json
 
 import typer
 
-from postgres_aiops.cli._common import TargetOption, cli_errors, console, get_connection
+from postgres_aiops.cli._common import TargetOption, audited, cli_errors, console, get_connection
 
 repl_app = typer.Typer(
     name="repl",
@@ -17,6 +17,7 @@ repl_app = typer.Typer(
 
 @repl_app.command("status")
 @cli_errors
+@audited
 def repl_status(target: TargetOption = None) -> None:
     """Connected standbys and replay lag."""
     from postgres_aiops.ops import replication as ops
@@ -27,6 +28,7 @@ def repl_status(target: TargetOption = None) -> None:
 
 @repl_app.command("slots")
 @cli_errors
+@audited
 def repl_slots(target: TargetOption = None) -> None:
     """Replication slots (inactive slots flagged)."""
     from postgres_aiops.ops import replication as ops
@@ -37,6 +39,7 @@ def repl_slots(target: TargetOption = None) -> None:
 
 @repl_app.command("wal")
 @cli_errors
+@audited
 def repl_wal(target: TargetOption = None) -> None:
     """WAL position, level and archiver health."""
     from postgres_aiops.ops import replication as ops

{postgres_aiops-0.10.2 → postgres_aiops-0.11.0}/postgres_aiops/cli/server.py

@@ -7,7 +7,7 @@ from typing import Annotated
 
 import typer
 
-from postgres_aiops.cli._common import TargetOption, cli_errors, console, get_connection
+from postgres_aiops.cli._common import TargetOption, audited, cli_errors, console, get_connection
 
 server_app = typer.Typer(
     name="server",
@@ -18,6 +18,7 @@ server_app = typer.Typer(
 
 @server_app.command("version")
 @cli_errors
+@audited
 def server_version(target: TargetOption = None) -> None:
     """Server version, uptime and recovery state."""
     from postgres_aiops.ops import server as ops
@@ -28,6 +29,7 @@ def server_version(target: TargetOption = None) -> None:
 
 @server_app.command("settings")
 @cli_errors
+@audited
 def server_settings(
     pattern: Annotated[str | None, typer.Argument(help="Name substring filter")] = None,
     target: TargetOption = None,
@@ -41,6 +43,7 @@ def server_settings(
 
 @server_app.command("extensions")
 @cli_errors
+@audited
 def server_extensions(target: TargetOption = None) -> None:
     """Installed extensions."""
     from postgres_aiops.ops import server as ops
@@ -51,6 +54,7 @@ def server_extensions(target: TargetOption = None) -> None:
 
 @server_app.command("databases")
 @cli_errors
+@audited
 def server_databases(target: TargetOption = None) -> None:
     """Databases with owner, encoding and size."""
     from postgres_aiops.ops import server as ops
@@ -61,6 +65,7 @@ def server_databases(target: TargetOption = None) -> None:
 
 @server_app.command("roles")
 @cli_errors
+@audited
 def server_roles(target: TargetOption = None) -> None:
     """Roles and their attributes."""
     from postgres_aiops.ops import server as ops

{postgres_aiops-0.10.2 → postgres_aiops-0.11.0}/postgres_aiops/cli/table.py

@@ -8,6 +8,7 @@ import typer
 
 from postgres_aiops.cli._common import (
     TargetOption,
+    audited,
     cli_errors,
     get_connection,
     print_result,
@@ -22,6 +23,7 @@ table_app = typer.Typer(
 
 @table_app.command("sizes")
 @cli_errors
+@audited
 def table_sizes(
     limit: Annotated[int, typer.Option("--limit", help="Tables to return")] = 20,
     target: TargetOption = None,
@@ -35,6 +37,7 @@ def table_sizes(
 
 @table_app.command("bloat")
 @cli_errors
+@audited
 def table_bloat(
     limit: Annotated[int, typer.Option("--limit", help="Tables to inspect")] = 50,
     target: TargetOption = None,
@@ -48,6 +51,7 @@ def table_bloat(
 
 @table_app.command("autovacuum")
 @cli_errors
+@audited
 def table_autovacuum(
     limit: Annotated[int, typer.Option("--limit", help="Tables to inspect")] = 50,
     target: TargetOption = None,

{postgres_aiops-0.10.2 → postgres_aiops-0.11.0}/postgres_aiops/ops/analysis.py

@@ -201,6 +201,22 @@ def _descendants(root: int, children: dict[int, list[int]]) -> set[int]:
     return seen
 
 
+def _lock_root_action(pid: int, idle: bool | None) -> str:
+    if idle:
+        return (
+            f"Backend {pid} heads the chain but is not running a statement (see "
+            "rootState: an open transaction, or session-level locks): rootQuery is "
+            "the last statement it ran, not a running one. cancel_query has nothing "
+            f"to cancel; terminate_backend({pid}) ends the session, rolling back any "
+            "transaction and releasing its locks — confirm with its owner first."
+        )
+    return (
+        f"Backend {pid} is the head of the chain — investigate its transaction; "
+        f"cancel_query({pid}) to stop its statement, or terminate_backend({pid}) to "
+        "end the session and release the locks."
+    )
+
+
 def blocking_lock_chain_rca(pairs: list[dict]) -> dict:
     """[READ] Build the wait-for tree from blocking pairs and name the root blocker.
 
@@ -217,7 +233,8 @@ def blocking_lock_chain_rca(pairs: list[dict]) -> dict:
         return {"blockedBackends": 0, "roots": [], "note": "No blocking detected."}
 
     children: dict[int, list[int]] = {}
-    blocking_query: dict[int, str] = {}
+    blocking_query: dict[int, str | None] = {}
+    blocking_state: dict[int, str | None] = {}
     blocked_pids: set[int] = set()
     blocking_pids: set[int] = set()
     for e in edges:
@@ -225,7 +242,8 @@ def blocking_lock_chain_rca(pairs: list[dict]) -> dict:
         children.setdefault(g, []).append(b)
         blocked_pids.add(b)
         blocking_pids.add(g)
-        blocking_query.setdefault(g, e.get("blockingQuery") or "")
+        blocking_query.setdefault(g, e.get("blockingQuery"))
+        blocking_state.setdefault(g, e.get("blockingState"))
 
     root_pids = [pid for pid in blocking_pids if pid not in blocked_pids]
     if not root_pids:
@@ -242,16 +260,18 @@ def blocking_lock_chain_rca(pairs: list[dict]) -> dict:
     roots = []
     for pid in root_pids:
         blocked = _descendants(pid, children)
+        state = blocking_state.get(pid)
+        # Any idle state means no statement is running: "idle in transaction"
+        # holds row locks, plain "idle" can still hold session-level advisory locks.
+        idle = None if state is None else str(state).startswith("idle")
         roots.append({
             "rootPid": pid,
             "blockedCount": len(blocked),
             "blockedPids": sorted(blocked),
-            "rootQuery": blocking_query.get(pid, ""),
-            "action": (
-                f"Backend {pid} is the head of the chain — investigate its "
-                "transaction; cancel_query(pid) to stop its statement, or "
-                "terminate_backend(pid) to end the session and release the locks."
-            ),
+            "rootQuery": blocking_query.get(pid),
+            "rootState": state,
+            "rootIdle": idle,
+            "action": _lock_root_action(pid, idle),
         })
     roots.sort(key=lambda r: r["blockedCount"], reverse=True)
     return {

{postgres_aiops-0.10.2 → postgres_aiops-0.11.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "postgres-aiops"
-version = "0.10.2"
+version = "0.11.0"
 description = "Governed AI-ops for PostgreSQL DBA operations: slow-query RCA, bloat/vacuum & blocking-lock analysis with a built-in governance harness (audit, budget, undo, risk tiers)"
 readme = "README.md"
 license = "MIT"

{postgres_aiops-0.10.2 → postgres_aiops-0.11.0}/server.json

@@ -7,12 +7,12 @@
     "url": "https://github.com/AIops-tools/Postgres-AIops",
     "source": "github"
   },
-  "version": "0.10.2",
+  "version": "0.11.0",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "postgres-aiops",
-      "version": "0.10.2",
+      "version": "0.11.0",
       "transport": {
         "type": "stdio"
       }

{postgres_aiops-0.10.2 → postgres_aiops-0.11.0}/skills/postgres-aiops/references/agent-guardrails.md

@@ -28,7 +28,7 @@ recorded on the audit row; they are never required and never block a call.
 ## What still needs a prompt
 
 These are model-behaviour problems the harness cannot fix from the outside.
-Copy this into your agent's system prompt:
+Recommended setup for a local model (adapt it to your agent client):
 
 ```text
 You operate a PostgreSQL server through the postgres-aiops MCP tools.

{postgres_aiops-0.10.2 → postgres_aiops-0.11.0}/skills/postgres-aiops/references/capabilities.md

@@ -32,7 +32,7 @@
 | `wal_status` | WAL fns + `pg_stat_archiver` | currentLsn, walLevel, max/minWalSize, archiver |
 | `slow_query_rca` | pg_stat_statements + EXPLAIN | worst{}, findings[] (cited cause/action) |
 | `bloat_and_vacuum_analysis` | table-bloat rows | recommendations[] (cited reasons + action) |
-| `blocking_lock_chain_rca` | `pg_blocking_pids` pairs | roots[], worstRootPid, deadlockSuspected |
+| `blocking_lock_chain_rca` | `pg_blocking_pids` pairs | roots[] (rootQuery, rootState, rootIdle — true for any `idle*` state; rootQuery is then the last statement run, not a running one — and action), worstRootPid, deadlockSuspected |
 | `undo_list` | local undo store | recorded, not-yet-applied reversible writes: undoId, ts, originalTool, inverseTool, note |
 
 The flagship analyses accept injected records (`statements=` / `tables=` /

{postgres_aiops-0.10.2 → postgres_aiops-0.11.0}/tests/test_analysis.py

@@ -82,3 +82,48 @@ def test_blocking_chain_detects_cycle():
 def test_blocking_chain_no_blocking():
     out = analysis.blocking_lock_chain_rca([])
     assert out["blockedBackends"] == 0
+
+
+# ── lock-chain root that is idle inside an open transaction ──────────────────
+
+
+def _pg_pairs(state, query="UPDATE t SET v=1 WHERE id=1"):
+    return [{"blockedPid": 201, "blockingPid": 100, "blockedQuery": "DELETE FROM t",
+             "blockingQuery": query, "blockingState": state}]
+
+
+def test_idle_in_transaction_root_is_named_and_cancel_is_ruled_out():
+    from postgres_aiops.ops import analysis as a
+
+    (root,) = a.blocking_lock_chain_rca(_pg_pairs("idle in transaction"))["roots"]
+    assert root["rootState"] == "idle in transaction"
+    assert root["rootIdle"] is True
+    # The query is the LAST statement it ran, not a running one.
+    assert "last statement" in root["action"]
+    assert "terminate_backend(100)" in root["action"]
+    assert "nothing to cancel" in root["action"]
+
+
+def test_active_root_offers_cancel_first():
+    from postgres_aiops.ops import analysis as a
+
+    (root,) = a.blocking_lock_chain_rca(_pg_pairs("active"))["roots"]
+    assert root["rootIdle"] is False
+    assert "cancel_query(100)" in root["action"]
+
+
+def test_missing_root_query_stays_null():
+    from postgres_aiops.ops import analysis as a
+
+    (root,) = a.blocking_lock_chain_rca(_pg_pairs(None, query=None))["roots"]
+    assert root["rootQuery"] is None
+    assert root["rootState"] is None
+    assert root["rootIdle"] is None  # state unknown
+
+
+def test_plain_idle_root_with_session_locks_is_not_offered_cancel():
+    from postgres_aiops.ops import analysis as a
+
+    (root,) = a.blocking_lock_chain_rca(_pg_pairs("idle"))["roots"]
+    assert root["rootIdle"] is True
+    assert "terminate_backend(100)" in root["action"]