feat(decisions): add list_decisions method [skip-runtime-e2e] (#186)

* feat(decisions): add list_decisions client method (#1982)

Python SDK piece of the 5-SDK γ fanout for axonflow-enterprise#1982.
Companion to explain_decision; both implement the ADR-043 decision
record contract with the same parity discipline.

## Added

- AxonFlow.list_decisions(opts: ListDecisionsOptions | None) ->
  list[DecisionSummary] hitting GET /api/v1/decisions.
- DecisionSummary (pydantic, extra='ignore') — slim 5-field row.
  policy_id + tool_signature are Optional because pre-α1 audit rows
  + dynamic-only blocks may not populate them.
- ListDecisionsOptions — every filter Optional[X]=None; None values
  omitted from the URL so the platform applies tier defaults.
- Extended exceptions.RateLimitError with new optional kwargs
  (limit_type, tier, upgrade) plus a new UpgradeInfo type. Backwards
  compatible — existing daily-quota callers keep their signature.
- _build_list_decisions_query helper at module scope (testable in
  isolation; used by list_decisions).
- examples/list_decisions.py — operator example mirroring
  examples/quickstart.py shape; surfaces RateLimitError.upgrade.

## Tests

10 new contract tests in tests/test_decisions.py:
- DecisionSummaryShape (minimum + full + extra-fields-ignored)
- happy path (3-row payload)
- filter serialization (every filter lands in URL)
- empty/partial options omit None fields
- 429 → RateLimitError with parsed envelope
- 429 with malformed body → RateLimitError without upgrade context
  (never silently succeed)
- 401 surfaces as AxonFlowError
- forward-compat — additive unknown fields on summaries + envelope
- _build_list_decisions_query unit (None / empty / partial)

pytest tests/test_decisions.py: 23 passed (including the 13 pre-existing).

## Runtime-e2e proof

Against setup-e2e-testing.sh enterprise stack on
axonflow-enterprise@feat/decisions-list-endpoint:

  $ source /tmp/axonflow-e2e-env.sh
  $ AXONFLOW_LIST_LIMIT=5 python examples/list_decisions.py
  === Recent decisions (2) ===
    2026-05-07T14:13:38.464545+00:00 deny  f6029a9b-...  policy=- tool=-
    2026-05-07T14:13:38.453107+00:00 deny  2575a3fe-...  policy=- tool=-

⛔ Do not merge — V1.1 release window.

Signed-off-by: Saurabh Jain <saurabhjain1592@gmail.com>

* fix(lint): drop Greek session labels + fix line-length + var name (#1982)

Ruff trips:
- RUF002/RUF003 on Greek-letter session labels (α1, γ) in docstrings
  and comments. Replace with plain "list_decisions" / "pre-V1.1".
- E741 ambiguous variable `l` in examples/list_decisions.py — rename
  to `lim`.
- E501 long lines on the 429 envelope wording in tests + example.
  Wrap into parenthesized string concatenation.

23 unit tests still green.

Signed-off-by: Saurabh Jain <saurabhjain1592@gmail.com>

* fix(lint): refresh falsey-clobber baseline + harden 429 envelope parse (#1982)

CI's falsey-clobber lint compares findings against a baseline keyed by
absolute line numbers. Inserting list_decisions (~106 lines) shifted
every pre-existing pattern below it down by the same amount; the
linter therefore reported 18 NEW findings + 18 stale baseline entries
(same set, different lines).

This commit:
- Refreshes .lint_baselines/falsey_clobber.json so the existing
  patterns are recognised at their new line numbers (no behaviour
  change — same 18 patterns, same files; only positions updated).
- Rewrites the new list_decisions 429 path to use `is None` /
  isinstance() guards instead of `or` fallbacks, so the new code
  contributes ZERO falsey-clobber findings to the baseline. Behaviour
  is identical: missing/non-string error -> "rate limit exceeded";
  missing/non-numeric limit/remaining -> 0; non-list decisions -> [].

Signed-off-by: Saurabh Jain <saurabhjain1592@gmail.com>

* fix(lint): apply ruff format to list_decisions 429 path (#1982)

Ruff formatter wanted the conditional remaining=... expression on a
single line; my hand-formatted multi-line version triggered
`ruff format --check` failure in CI. Behaviour is unchanged — only
whitespace normalised.

Signed-off-by: Saurabh Jain <saurabhjain1592@gmail.com>

* fix(lint): re-refresh falsey-clobber baseline after ruff reformat (#1982)

Ruff formatter collapsed a 3-line conditional in
list_decisions onto a single line, shifting line 6208's
`executions or []` pattern up to line 6206. The previous
baseline refresh keyed it to :6208; refresh again so the
post-format positions match.

No behaviour change. Same 65 pre-existing findings, same files;
only positions adjusted.

Signed-off-by: Saurabh Jain <saurabhjain1592@gmail.com>

---------

Signed-off-by: Saurabh Jain <saurabhjain1592@gmail.com>

Author: saurabhjain1592

.lint_baselines/falsey_clobber.json

@@ -22,24 +22,24 @@
     "axonflow/adapters/tool_wrapper.py:190:20",
     "axonflow/adapters/tool_wrapper.py:208:20",
     "axonflow/adapters/tool_wrapper.py:220:20",
-    "axonflow/client.py:1065:16",
-    "axonflow/client.py:1142:16",
-    "axonflow/client.py:1614:37",
-    "axonflow/client.py:1655:18",
-    "axonflow/client.py:1713:37",
-    "axonflow/client.py:2231:24",
-    "axonflow/client.py:2252:33",
-    "axonflow/client.py:2253:31",
-    "axonflow/client.py:2265:25",
-    "axonflow/client.py:2326:28",
-    "axonflow/client.py:2367:69",
-    "axonflow/client.py:286:14",
-    "axonflow/client.py:291:24",
-    "axonflow/client.py:292:20",
-    "axonflow/client.py:488:44",
-    "axonflow/client.py:6074:25",
-    "axonflow/client.py:799:20",
-    "axonflow/client.py:885:20",
+    "axonflow/client.py:1100:16",
+    "axonflow/client.py:1177:16",
+    "axonflow/client.py:1649:37",
+    "axonflow/client.py:1690:18",
+    "axonflow/client.py:1748:37",
+    "axonflow/client.py:2266:24",
+    "axonflow/client.py:2287:33",
+    "axonflow/client.py:2288:31",
+    "axonflow/client.py:2300:25",
+    "axonflow/client.py:2361:28",
+    "axonflow/client.py:2402:69",
+    "axonflow/client.py:292:14",
+    "axonflow/client.py:297:24",
+    "axonflow/client.py:298:20",
+    "axonflow/client.py:523:44",
+    "axonflow/client.py:6206:25",
+    "axonflow/client.py:834:20",
+    "axonflow/client.py:920:20",
     "axonflow/execution.py:205:19",
     "axonflow/interceptors/anthropic.py:134:43",
     "axonflow/interceptors/anthropic.py:161:43",

axonflow/client.py

@@ -78,7 +78,11 @@
     ValidateGitProviderRequest,
     ValidateGitProviderResponse,
 )
-from axonflow.decisions import DecisionExplanation
+from axonflow.decisions import (
+    DecisionExplanation,
+    DecisionSummary,
+    ListDecisionsOptions,
+)
 from axonflow.exceptions import (
     AuthenticationError,
     AxonFlowError,
@@ -88,7 +92,9 @@
     IdempotencyKeyMismatchError,
     PlanExecutionError,
     PolicyViolationError,
+    RateLimitError,
     TimeoutError,
+    UpgradeInfo,
     VersionConflictError,
 )
 from axonflow.execution import (
@@ -385,6 +391,35 @@ def _parse_pending_approvals_response(response: dict[str, Any]) -> PendingApprov
     )
 
 
+def _build_list_decisions_query(opts: ListDecisionsOptions | None) -> str:
+    """Serialize :class:`ListDecisionsOptions` into the URL query string.
+
+    ``None`` values are omitted so the platform applies its tier-default
+    page. Stable field order so test mocks can match the URL exactly.
+    """
+    if opts is None:
+        return ""
+    pairs: list[tuple[str, str]] = []
+    if opts.since is not None:
+        # Use the "Z" suffix for UTC; isoformat() emits +00:00 which
+        # would urlencode to %2B00%3A00 and over-noise the URL. The
+        # platform parses both, but the Z form matches the explain
+        # endpoint's response shape byte-for-byte.
+        ts = opts.since
+        if ts.utcoffset() is not None:
+            ts = ts.astimezone(tz=ts.tzinfo).replace(tzinfo=None)
+        pairs.append(("since", ts.strftime("%Y-%m-%dT%H:%M:%SZ")))
+    if opts.decision is not None:
+        pairs.append(("decision", opts.decision))
+    if opts.policy_id is not None:
+        pairs.append(("policy_id", opts.policy_id))
+    if opts.tool_signature is not None:
+        pairs.append(("tool_signature", opts.tool_signature))
+    if opts.limit is not None:
+        pairs.append(("limit", str(opts.limit)))
+    return urlencode(pairs)
+
+
 def _build_audit_search_body(request: AuditSearchRequest) -> dict[str, Any]:
     """Build the POST /api/v1/audit/search body from an AuditSearchRequest.
 
@@ -2737,6 +2772,103 @@ async def explain_decision(self, decision_id: str) -> DecisionExplanation:
             response = {}
         return DecisionExplanation.model_validate(response)
 
+    async def list_decisions(
+        self,
+        opts: ListDecisionsOptions | None = None,
+    ) -> list[DecisionSummary]:
+        """List recent policy decisions for the caller's tenant.
+
+        Implements ``GET /api/v1/decisions``. Returns the slim 5-field
+        :class:`DecisionSummary` page; the platform applies a tier-gated
+        cap (5/24h Free + Community, 100/30d Pro + Evaluation, 1000/full
+        retention Enterprise). Over-cap requests yield a 429 with the V1
+        upgrade envelope, surfaced as
+        :class:`axonflow.exceptions.RateLimitError` carrying the parsed
+        ``upgrade.{tier,compare_url,buy_url}`` so the caller can branch on
+        them without re-parsing the body.
+
+        Args:
+            opts: Filter + page-size options. ``None`` returns the
+                tier-default page from the caller's tenant.
+
+        Returns:
+            A list of DecisionSummary rows ordered newest-first.
+
+        Raises:
+            RateLimitError: 429 tier-cap; ``rle.upgrade`` exposes
+                tier/compare_url/buy_url.
+            AxonFlowError: Other HTTP errors (401, 5xx, etc.).
+
+        Example:
+            >>> from axonflow.decisions import ListDecisionsOptions
+            >>> opts = ListDecisionsOptions(decision="deny", limit=10)
+            >>> for d in await client.list_decisions(opts):
+            ...     print(d.decision_id, d.decision, d.timestamp)
+        """
+        path = "/api/v1/decisions"
+        qs = _build_list_decisions_query(opts)
+        if qs:
+            path = f"{path}?{qs}"
+
+        # Hand-roll the request so we can branch on 429 BEFORE
+        # raise_for_status promotes it to a generic AxonFlowError.
+        # Other failure modes fall through to the same shape
+        # _orchestrator_request would have produced.
+        self._pre_request_hook()
+        url = f"{self._config.endpoint}{path}"
+        try:
+            response = await self._http_client.get(url)
+        except httpx.ConnectError as e:
+            msg = f"Failed to connect to Orchestrator: {e}"
+            raise ConnectionError(msg) from e
+        except httpx.TimeoutException as e:
+            msg = f"Request timed out: {e}"
+            raise TimeoutError(msg) from e
+
+        if response.status_code == 429:  # noqa: PLR2004
+            # Try to parse the V1 envelope. Malformed body falls back to
+            # a plain RateLimitError without upgrade context — never
+            # silently succeed.
+            try:
+                envelope = response.json()
+            except (ValueError, json.JSONDecodeError):
+                envelope = {}
+            limit_type = envelope.get("limit_type")
+            upgrade_dict = envelope.get("upgrade")
+            upgrade = None
+            if isinstance(upgrade_dict, dict):
+                upgrade = UpgradeInfo(
+                    tier=upgrade_dict.get("tier", ""),
+                    wording=upgrade_dict.get("wording", ""),
+                    compare_url=upgrade_dict.get("compare_url", ""),
+                    buy_url=upgrade_dict.get("buy_url", ""),
+                )
+            error_msg = envelope.get("error")
+            if not isinstance(error_msg, str) or error_msg == "":
+                error_msg = "rate limit exceeded"
+            raw_limit = envelope.get("limit")
+            raw_remaining = envelope.get("remaining")
+            raise RateLimitError(
+                error_msg,
+                limit=int(raw_limit) if isinstance(raw_limit, (int, float)) else 0,
+                remaining=(int(raw_remaining) if isinstance(raw_remaining, (int, float)) else 0),
+                limit_type=limit_type,
+                tier=envelope.get("tier"),
+                upgrade=upgrade,
+            )
+
+        if response.status_code >= 400:  # noqa: PLR2004
+            msg = f"HTTP {response.status_code}: {response.text}"
+            raise AxonFlowError(msg)
+
+        body = response.json()
+        if not isinstance(body, dict):
+            return []
+        rows = body.get("decisions")
+        if not isinstance(rows, list):
+            return []
+        return [DecisionSummary.model_validate(r) for r in rows]
+
     async def get_audit_logs_by_tenant(
         self,
         tenant_id: str,

axonflow/decisions.py

@@ -3,13 +3,17 @@
 Implements ADR-043 (Explainability Data Contract). The DecisionExplanation
 shape is frozen; additive-only changes are allowed; renames/removals require
 a major version bump.
+
+list_decisions companion (list_decisions / #1982) reuses the same conventions:
+DecisionSummary is the slim 5-field row; ListDecisionsOptions carries the
+5 optional filters.
 """
 
 from __future__ import annotations
 
 from datetime import datetime
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, ConfigDict, Field
 
 
 class ExplainPolicy(BaseModel):
@@ -69,3 +73,46 @@ class DecisionExplanation(BaseModel):
     historical_hit_count_session: int = 0
     policy_source_link: str | None = None
     tool_signature: str | None = None
+
+
+class DecisionSummary(BaseModel):
+    """Slim 5-field row returned by ``client.list_decisions``.
+
+    ``policy_id`` and ``tool_signature`` are optional because dynamic-only
+    blocks + pre-V1.1 audit rows may not populate them. Additive new fields
+    are non-breaking per ADR-043 §"Versioning"; arbitrary unknown fields
+    on the wire are accepted via ``extra='ignore'``.
+
+    Cross-SDK parity:
+
+      Go:     axonflow-sdk-go/decisions.go (DecisionSummary)
+      TS:     axonflow-sdk-typescript/src/types/decisions.ts (DecisionSummary)
+      Java:   .../sdk/types/DecisionSummary.java
+      Rust:   axonflow-sdk-rust/src/types/decisions.rs (DecisionSummary)
+    """
+
+    model_config = ConfigDict(extra="ignore")
+
+    decision_id: str
+    timestamp: datetime
+    decision: str  # allow | deny | require_approval
+    policy_id: str | None = None
+    tool_signature: str | None = None
+
+
+class ListDecisionsOptions(BaseModel):
+    """Optional filters for ``client.list_decisions``.
+
+    Every field is optional; ``None`` values are omitted from the URL so
+    the platform applies its tier-default page. ``decision`` must be one
+    of ``"allow"``, ``"deny"``, or ``"require_approval"`` when set.
+    ``limit`` is server-capped per tier; over-cap requests yield a 429
+    with the V1 upgrade envelope (surfaced as
+    :class:`axonflow.exceptions.RateLimitError`).
+    """
+
+    since: datetime | None = None
+    decision: str | None = None
+    policy_id: str | None = None
+    tool_signature: str | None = None
+    limit: int | None = None

axonflow/exceptions.py

@@ -42,23 +42,70 @@ def __init__(
         self.block_reason = block_reason
 
 
+class UpgradeInfo:
+    """Pricing-tier upgrade context emitted in a V1 429 envelope.
+
+    Mirrors the platform-side
+    feedback_429_no_upgrade_hint_is_conversion_gap.md contract.
+    Cross-SDK parity:
+
+      Go:     axonflow-sdk-go/decisions.go (UpgradeInfo)
+      TS:     axonflow-sdk-typescript/src/types/decisions.ts (UpgradeInfo)
+      Java:   .../sdk/types/UpgradeInfo.java
+      Rust:   axonflow-sdk-rust/src/types/decisions.rs (UpgradeInfo)
+    """
+
+    __slots__ = ("buy_url", "compare_url", "tier", "wording")
+
+    def __init__(
+        self,
+        tier: str,
+        wording: str,
+        compare_url: str,
+        buy_url: str,
+    ) -> None:
+        self.tier = tier
+        self.wording = wording
+        self.compare_url = compare_url
+        self.buy_url = buy_url
+
+
 class RateLimitError(AxonFlowError):
-    """Rate limit exceeded."""
+    """Rate limit exceeded.
+
+    Holds the parsed V1 429 envelope when available. ``limit_type`` and
+    ``tier`` and ``upgrade`` are populated for tier-cap 429s (e.g.
+    ``list_decisions`` page-size cap, daily-quota cap); legacy 429s
+    leave them ``None`` for backwards compatibility.
+    """
 
     def __init__(
         self,
         message: str,
         limit: int,
         remaining: int,
         reset_at: str | None = None,
+        *,
+        limit_type: str | None = None,
+        tier: str | None = None,
+        upgrade: UpgradeInfo | None = None,
     ) -> None:
         super().__init__(
             message,
-            details={"limit": limit, "remaining": remaining, "reset_at": reset_at},
+            details={
+                "limit": limit,
+                "remaining": remaining,
+                "reset_at": reset_at,
+                "limit_type": limit_type,
+                "tier": tier,
+            },
         )
         self.limit = limit
         self.remaining = remaining
         self.reset_at = reset_at
+        self.limit_type = limit_type
+        self.tier = tier
+        self.upgrade = upgrade
 
 
 class BudgetExceededError(AxonFlowError):