imperal-sdk 5.2.2__tar.gz → 5.4.0__tar.gz

{imperal_sdk-5.2.2 → imperal_sdk-5.4.0}/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 All notable changes to `imperal-sdk` are documented here.
 
+## 5.4.0 — 2026-06-16 — BillingClient portal + full Webbee parity
+
+Additive — **nothing to migrate**.
+
+### Added
+- `ctx.billing.create_billing_portal_session()` — mints a Stripe Customer
+  Portal session and returns its hosted URL (for `ui.Open`), so extensions can
+  let users manage cards + view invoices on Stripe's hosted page (PAN never
+  touches our backend). Surfaces errors.
+- Five `ctx.billing` parity methods so Webbee can fully drive billing via chat:
+  `list_plans()` (public plan catalog → `list[PlanInfo]`, safe-degrades to `[]`),
+  `get_auto_topup()` (→ `AutoTopupSettings`, safe-degrades to disabled defaults),
+  `set_auto_topup(enabled, threshold_pct=10, recharge_tokens=20000, payment_method_id="")`
+  (surfaces errors), `cancel_subscription()` (cancel-at-period-end → result dict,
+  surfaces errors), `update_billing_profile(profile)` (writes name/company/vat/country,
+  surfaces errors).
+- New dataclasses `PlanInfo` and `AutoTopupSettings` in `imperal_sdk.types.models`.
+
+## 5.3.0 — 2026-06-16 — BillingClient write/payment methods
+
+Additive — **nothing to migrate**.
+
+### Added
+- `ctx.billing` write/payment methods: `list_payment_methods`, `list_payments`,
+  `create_setup_intent`, `set_default_payment_method`, `remove_payment_method`,
+  `change_plan`, `topup`. Reads degrade safely; writes surface errors so the
+  caller can render Stripe failures / drive the Payment Element.
+- `BillingClient` now sends `X-Acting-User` on the service-token path so
+  `get_user_or_service` gateway endpoints resolve the acting user.
+
 ## 5.2.2 — 2026-06-11 — Import-light package root
 
 Performance / robustness release. **Zero API changes** — every public name,

{imperal_sdk-5.2.2 → imperal_sdk-5.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: imperal-sdk
-Version: 5.2.2
+Version: 5.4.0
 Summary: SDK for building Imperal Cloud extensions
 Author: Valentin Scerbacov, Imperal, Inc.
 License-Expression: AGPL-3.0-or-later

{imperal_sdk-5.2.2 → imperal_sdk-5.4.0}/api_surface.json

@@ -3,9 +3,16 @@
     "complete"
   ],
   "billing": [
+    "change_plan",
     "check_limits",
+    "create_setup_intent",
     "get_balance",
     "get_subscription",
+    "list_payment_methods",
+    "list_payments",
+    "remove_payment_method",
+    "set_default_payment_method",
+    "topup",
     "track_usage"
   ],
   "config": [

{imperal_sdk-5.2.2 → imperal_sdk-5.4.0}/sdk_claims.json

@@ -1,5 +1,5 @@
 {
-  "_sdk_version": "5.1.0",
+  "_sdk_version": "5.4.0",
   "constants": {
     "max_call_depth": {
       "counts_root": true,
@@ -17,11 +17,22 @@
     "long_running": "advisory"
   },
   "http_payloads": {
+    "POST /v1/billing/change-plan": [
+      "plan_id",
+      "period"
+    ],
     "POST /v1/billing/internal/usage/track": [
       "meter",
       "quantity",
       "user_id",
       "tenant_id"
+    ],
+    "POST /v1/billing/payment-methods/setup": [],
+    "POST /v1/billing/topup": [
+      "tokens",
+      "price_cents",
+      "save_payment_method",
+      "off_session"
     ]
   }
 }

{imperal_sdk-5.2.2 → imperal_sdk-5.4.0}/src/imperal_sdk/__init__.py

@@ -1,7 +1,7 @@
 """Imperal Cloud SDK — build extensions for the Imperal platform."""
 from typing import TYPE_CHECKING
 
-__version__ = "5.2.2"
+__version__ = "5.4.0"
 
 # 5.2.2 (2026-06-11): the package root resolves its public surface lazily
 # (PEP 562). The eager imports pulled the HTTP transport (Context / client

imperal_sdk-5.4.0/src/imperal_sdk/billing/client.py

@@ -0,0 +1,325 @@
+# Copyright (c) 2026 Imperal, Inc., Valentin Scerbacov, and contributors
+# Licensed under the AGPL-3.0 License. See LICENSE file for details.
+from __future__ import annotations
+import logging
+from dataclasses import dataclass
+from typing import Any
+import httpx
+
+from imperal_sdk.types.models import (
+    BalanceInfo, PaymentMethod, SetupIntentResult, ChangePlanResult,
+    TopupResult, PaymentRecord, PlanInfo, AutoTopupSettings,
+)
+
+log = logging.getLogger(__name__)
+
+
+@dataclass
+class LimitsResult:
+    plan: str
+    usage: dict[str, int]
+    limits: dict[str, int]
+    exceeded: list[str]
+
+    def is_exceeded(self, meter: str) -> bool:
+        return meter in self.exceeded
+
+    @property
+    def any_exceeded(self) -> bool:
+        return bool(self.exceeded)
+
+
+@dataclass
+class SubscriptionInfo:
+    plan: str
+    status: str
+    started_at: str | None = None
+    expires_at: str | None = None
+
+
+class BillingClient:
+    """Read-only billing client for extensions.
+
+    When initialized with service_token (kernel context), uses internal
+    endpoints with X-Service-Token header. When initialized with auth_token
+    (user JWT from Panel), uses public endpoints with Authorization header.
+    """
+
+    def __init__(
+        self, gateway_url: str, auth_token: str = "",
+        service_token: str = "", user_id: str = "",
+    ):
+        self._gateway_url = gateway_url.rstrip("/")
+        self._service_token = service_token
+        self._auth_token = auth_token
+        self._user_id = user_id
+
+    def _headers(self) -> dict:
+        if self._service_token:
+            h = {"X-Service-Token": self._service_token}
+            if self._user_id:
+                h["X-Acting-User"] = self._user_id
+            return h
+        return {"Authorization": f"Bearer {self._auth_token}"}
+
+    def _uid(self, user: Any = None) -> str:
+        return self._user_id or (getattr(user, "id", "") if user else "")
+
+    async def check_limits(self, user: Any = None) -> LimitsResult:
+        uid = self._uid(user)
+        try:
+            async with httpx.AsyncClient() as client:
+                if self._service_token and uid:
+                    resp = await client.get(
+                        f"{self._gateway_url}/v1/billing/internal/user-limits/{uid}",
+                        headers=self._headers(), timeout=10)
+                else:
+                    resp = await client.get(
+                        f"{self._gateway_url}/v1/billing/usage",
+                        headers=self._headers(), timeout=10)
+                resp.raise_for_status()
+                data = resp.json()
+                return LimitsResult(
+                    plan=data.get("plan", "free"),
+                    usage=data.get("usage", {}),
+                    limits=data.get("limits", {}),
+                    exceeded=data.get("exceeded", []),
+                )
+        except Exception as e:
+            log.warning("Billing check_limits failed: %s", e)
+            return LimitsResult(plan="unknown", usage={}, limits={}, exceeded=[])
+
+    async def get_subscription(self, user: Any = None) -> SubscriptionInfo:
+        uid = self._uid(user)
+        try:
+            async with httpx.AsyncClient() as client:
+                if self._service_token and uid:
+                    resp = await client.get(
+                        f"{self._gateway_url}/v1/billing/internal/subscription/{uid}",
+                        headers=self._headers(), timeout=10)
+                else:
+                    resp = await client.get(
+                        f"{self._gateway_url}/v1/billing/subscription",
+                        headers=self._headers(), timeout=10)
+                resp.raise_for_status()
+                data = resp.json()
+                return SubscriptionInfo(
+                    plan=data.get("plan", "free"),
+                    status=data.get("status", "unknown"),
+                    started_at=data.get("started_at"),
+                    expires_at=data.get("expires_at"),
+                )
+        except Exception as e:
+            log.warning("Billing get_subscription failed: %s", e)
+            return SubscriptionInfo(plan="unknown", status="unavailable")
+
+    async def track_usage(self, meter: str, quantity: int = 1, user: Any = None) -> bool:
+        """Track usage for a given meter. Returns True on success.
+
+        Requires service_token — usage tracking is a server-to-server operation.
+        The gateway endpoint is POST /v1/billing/internal/usage/track (service
+        token required). There is no public user-facing track endpoint; calling
+        without a service token logs a warning and returns False.
+        """
+        uid = self._uid(user)
+        if not self._service_token:
+            log.warning(
+                "Billing track_usage requires a service token; "
+                "no-token path is not supported (no public track endpoint). "
+                "Returning False without attempting the request."
+            )
+            return False
+        try:
+            async with httpx.AsyncClient() as client:
+                payload: dict = {"meter": meter, "quantity": quantity}
+                if uid:
+                    payload["user_id"] = uid
+                    payload["tenant_id"] = "default"
+                resp = await client.post(
+                    f"{self._gateway_url}/v1/billing/internal/usage/track",
+                    json=payload, headers=self._headers(), timeout=10)
+                return resp.status_code == 200
+        except Exception as e:
+            log.warning("Billing track_usage failed: %s", e)
+            return False
+
+    async def get_balance(self, user: Any = None) -> BalanceInfo:
+        """Get current token balance and plan cap."""
+        uid = self._uid(user)
+        try:
+            async with httpx.AsyncClient() as client:
+                if self._service_token and uid:
+                    resp = await client.get(
+                        f"{self._gateway_url}/v1/billing/internal/balance/{uid}",
+                        headers=self._headers(), timeout=10)
+                else:
+                    resp = await client.get(
+                        f"{self._gateway_url}/v1/billing/balance",
+                        headers=self._headers(), timeout=10)
+                resp.raise_for_status()
+                data = resp.json()
+                return BalanceInfo(
+                    balance=data.get("balance", 0),
+                    plan=data.get("plan", ""),
+                    cap=data.get("cap", 0),
+                )
+        except Exception as e:
+            log.warning("Billing get_balance failed: %s", e)
+            return BalanceInfo(balance=0, plan="unknown", cap=0)
+
+    # ─── Payment methods + plan changes + top-up + payment history ──────── #
+
+    async def list_payment_methods(self, user: Any = None) -> list[PaymentMethod]:
+        uid = self._uid(user)
+        try:
+            async with httpx.AsyncClient() as client:
+                url = (f"{self._gateway_url}/v1/billing/internal/payment-methods/{uid}"
+                       if (self._service_token and uid)
+                       else f"{self._gateway_url}/v1/billing/payment-methods")
+                resp = await client.get(url, headers=self._headers(), timeout=10)
+                resp.raise_for_status()
+                return [PaymentMethod(**m) for m in resp.json()]
+        except Exception as e:
+            log.warning("Billing list_payment_methods failed: %s", e)
+            return []
+
+    async def list_payments(self, user: Any = None, limit: int = 50, offset: int = 0) -> list[PaymentRecord]:
+        uid = self._uid(user)
+        try:
+            async with httpx.AsyncClient() as client:
+                if self._service_token and uid:
+                    url = f"{self._gateway_url}/v1/billing/internal/payments/{uid}"
+                else:
+                    url = f"{self._gateway_url}/v1/billing/payments"
+                resp = await client.get(url, headers=self._headers(),
+                                        params={"limit": limit, "offset": offset}, timeout=15)
+                resp.raise_for_status()
+                return [PaymentRecord(**p) for p in resp.json()]
+        except Exception as e:
+            log.warning("Billing list_payments failed: %s", e)
+            return []
+
+    async def create_setup_intent(self, user: Any = None) -> SetupIntentResult:
+        """Add-card SetupIntent. Surfaces errors (the ext needs the client secret)."""
+        async with httpx.AsyncClient() as client:
+            resp = await client.post(f"{self._gateway_url}/v1/billing/payment-methods/setup",
+                                     headers=self._headers(), timeout=10)
+            resp.raise_for_status()
+            d = resp.json()
+            return SetupIntentResult(client_secret=d.get("client_secret", ""),
+                                     publishable_key=d.get("publishable_key", ""))
+
+    async def set_default_payment_method(self, pm_id: str, user: Any = None) -> bool:
+        async with httpx.AsyncClient() as client:
+            resp = await client.put(f"{self._gateway_url}/v1/billing/payment-methods/{pm_id}/default",
+                                    headers=self._headers(), timeout=10)
+            resp.raise_for_status()
+            return True
+
+    async def remove_payment_method(self, pm_id: str, user: Any = None) -> bool:
+        async with httpx.AsyncClient() as client:
+            resp = await client.delete(f"{self._gateway_url}/v1/billing/payment-methods/{pm_id}",
+                                       headers=self._headers(), timeout=10)
+            resp.raise_for_status()
+            return True
+
+    async def change_plan(self, plan_id: str, period: str = "monthly", user: Any = None) -> ChangePlanResult:
+        """Upgrade (prorated, immediate) / downgrade (scheduled). Surfaces errors."""
+        async with httpx.AsyncClient() as client:
+            resp = await client.post(f"{self._gateway_url}/v1/billing/change-plan",
+                                     json={"plan_id": plan_id, "period": period},
+                                     headers=self._headers(), timeout=15)
+            resp.raise_for_status()
+            d = resp.json()
+            return ChangePlanResult(
+                action=d.get("action", ""), plan=d.get("plan", ""),
+                succeeded=bool(d.get("succeeded", False)),
+                requires_action=bool(d.get("requires_action", False)),
+                client_secret=d.get("client_secret", ""),
+                effective_at=d.get("effective_at", "") or "",
+                pending=bool(d.get("pending", False)))
+
+    async def topup(self, tokens: int, price_cents: int, save_payment_method: bool = True,
+                    off_session: bool = True, user: Any = None) -> TopupResult:
+        """Token top-up PaymentIntent. Surfaces errors.
+
+        With ``off_session=True`` (default) the gateway attempts an immediate
+        off-session charge against the saved card and returns ``succeeded`` /
+        ``requires_action``. The Element path (``off_session=False``) returns
+        the ``client_secret`` instead.
+        """
+        async with httpx.AsyncClient() as client:
+            resp = await client.post(f"{self._gateway_url}/v1/billing/topup",
+                                     json={"tokens": tokens, "price_cents": price_cents,
+                                           "save_payment_method": save_payment_method,
+                                           "off_session": off_session},
+                                     headers=self._headers(), timeout=15)
+            resp.raise_for_status()
+            d = resp.json()
+            return TopupResult(client_secret=d.get("client_secret", ""),
+                               payment_intent_id=d.get("payment_intent_id", ""),
+                               publishable_key=d.get("publishable_key", ""),
+                               succeeded=bool(d.get("succeeded", False)),
+                               requires_action=bool(d.get("requires_action", False)))
+
+    async def create_billing_portal_session(self, user: Any = None) -> str:
+        """Create a Stripe Customer Portal session and return its hosted URL.
+        Surfaces errors (the ext needs the URL)."""
+        async with httpx.AsyncClient() as client:
+            resp = await client.post(f"{self._gateway_url}/v1/billing/portal",
+                                     headers=self._headers(), timeout=10)
+            resp.raise_for_status()
+            return resp.json().get("url", "")
+
+    async def list_plans(self, user: Any = None) -> list[PlanInfo]:
+        """Public plan catalog. Safe-degrades to []."""
+        try:
+            async with httpx.AsyncClient() as client:
+                resp = await client.get(f"{self._gateway_url}/v1/billing/plans",
+                                        headers=self._headers(), timeout=10)
+                resp.raise_for_status()
+                return [PlanInfo(**p) for p in resp.json()]
+        except Exception as e:
+            log.warning("Billing list_plans failed: %s", e)
+            return []
+
+    async def get_auto_topup(self, user: Any = None) -> AutoTopupSettings:
+        """Safe-degrades to disabled defaults."""
+        uid = self._uid(user)
+        try:
+            async with httpx.AsyncClient() as client:
+                resp = await client.get(f"{self._gateway_url}/v1/billing/auto-topup",
+                                        headers=self._headers(), timeout=10)
+                resp.raise_for_status()
+                return AutoTopupSettings(**resp.json())
+        except Exception as e:
+            log.warning("Billing get_auto_topup failed: %s", e)
+            return AutoTopupSettings()
+
+    async def set_auto_topup(self, enabled: bool, threshold_pct: int = 10,
+                             recharge_tokens: int = 20000, payment_method_id: str = "",
+                             user: Any = None) -> bool:
+        """Surfaces errors."""
+        async with httpx.AsyncClient() as client:
+            resp = await client.put(f"{self._gateway_url}/v1/billing/auto-topup",
+                json={"enabled": enabled, "threshold_pct": threshold_pct,
+                      "recharge_tokens": recharge_tokens, "payment_method_id": payment_method_id},
+                headers=self._headers(), timeout=10)
+            resp.raise_for_status()
+            return True
+
+    async def cancel_subscription(self, user: Any = None) -> dict:
+        """Cancel at period end. Surfaces errors. Returns the gateway result dict."""
+        async with httpx.AsyncClient() as client:
+            resp = await client.post(f"{self._gateway_url}/v1/billing/cancel",
+                                     headers=self._headers(), timeout=15)
+            resp.raise_for_status()
+            return resp.json() if resp.content else {}
+
+    async def update_billing_profile(self, profile: dict, user: Any = None) -> bool:
+        """Surfaces errors. profile keys: name/company/vat/country."""
+        async with httpx.AsyncClient() as client:
+            resp = await client.put(f"{self._gateway_url}/v1/billing/profile",
+                                    json=profile, headers=self._headers(), timeout=10)
+            resp.raise_for_status()
+            return True

{imperal_sdk-5.2.2 → imperal_sdk-5.4.0}/src/imperal_sdk/context.py

@@ -50,6 +50,19 @@ class BillingProtocol(Protocol):
     async def get_subscription(self) -> SubscriptionInfo: ...
     async def track_usage(self, meter: str, quantity: int = 1, user: Any = None) -> bool: ...
     async def get_balance(self) -> BalanceInfo: ...
+    async def list_payment_methods(self, user: Any = None) -> list: ...
+    async def list_payments(self, user: Any = None, limit: int = 50, offset: int = 0) -> list: ...
+    async def create_setup_intent(self, user: Any = None): ...
+    async def set_default_payment_method(self, pm_id: str, user: Any = None) -> bool: ...
+    async def remove_payment_method(self, pm_id: str, user: Any = None) -> bool: ...
+    async def change_plan(self, plan_id: str, period: str = "monthly", user: Any = None): ...
+    async def topup(self, tokens: int, price_cents: int, save_payment_method: bool = True, off_session: bool = True, user: Any = None): ...
+    async def create_billing_portal_session(self, user: Any = None) -> str: ...
+    async def list_plans(self, user: Any = None) -> list: ...
+    async def get_auto_topup(self, user: Any = None): ...
+    async def set_auto_topup(self, enabled: bool, threshold_pct: int = 10, recharge_tokens: int = 20000, payment_method_id: str = "", user: Any = None) -> bool: ...
+    async def cancel_subscription(self, user: Any = None) -> dict: ...
+    async def update_billing_profile(self, profile: dict, user: Any = None) -> bool: ...
 
 
 @runtime_checkable

{imperal_sdk-5.2.2 → imperal_sdk-5.4.0}/src/imperal_sdk/devtools/generate_sdk_claims.py

@@ -35,6 +35,9 @@ _DECORATOR_ROLES = {
 # stale 'amount' field must never reappear here.
 _HTTP_PAYLOADS: dict[str, list[str]] = {
     "POST /v1/billing/internal/usage/track": ["meter", "quantity", "user_id", "tenant_id"],
+    "POST /v1/billing/change-plan": ["plan_id", "period"],
+    "POST /v1/billing/topup": ["tokens", "price_cents", "save_payment_method", "off_session"],
+    "POST /v1/billing/payment-methods/setup": [],
 }
 
 

{imperal_sdk-5.2.2 → imperal_sdk-5.4.0}/src/imperal_sdk/types/models.py

@@ -123,3 +123,79 @@ class HTTPStatusError(Exception):
         self.status_code = status_code
         self.body = body or ""
         super().__init__(f"HTTP {status_code}: {str(body)[:200]}")
+
+
+@dataclass
+class PaymentMethod:
+    """Result item from ctx.billing.list_payment_methods()."""
+    id: str = ""
+    type: str = "card"
+    brand: str = ""
+    last4: str = ""
+    exp_month: int = 0
+    exp_year: int = 0
+    is_default: bool = False
+
+
+@dataclass
+class SetupIntentResult:
+    """Result from ctx.billing.create_setup_intent() — drives a Stripe add-card flow."""
+    client_secret: str = ""
+    publishable_key: str = ""
+
+
+@dataclass
+class ChangePlanResult:
+    """Result from ctx.billing.change_plan()."""
+    action: str = ""
+    plan: str = ""
+    succeeded: bool = False
+    requires_action: bool = False
+    client_secret: str = ""
+    effective_at: str = ""
+    pending: bool = False
+
+
+@dataclass
+class TopupResult:
+    """Result from ctx.billing.topup() — drives a Stripe Payment Element."""
+    client_secret: str = ""
+    payment_intent_id: str = ""
+    publishable_key: str = ""
+    succeeded: bool = False
+    requires_action: bool = False
+
+
+@dataclass
+class PaymentRecord:
+    """Result item from ctx.billing.list_payments()."""
+    payment_intent_id: str = ""
+    amount_cents: int = 0
+    currency: str = "usd"
+    tokens: int = 0
+    status: str = ""
+    type: str = ""
+    created_at: str | None = None
+    completed_at: str | None = None
+    receipt_url: str = ""
+
+
+@dataclass
+class PlanInfo:
+    """Result item from ctx.billing.list_plans() — the public plan catalog."""
+    id: str = ""
+    name: str = ""
+    price: float = 0.0
+    interval: str = "monthly"
+    features: dict = field(default_factory=dict)
+    limits: dict = field(default_factory=dict)
+
+
+@dataclass
+class AutoTopupSettings:
+    """Result from ctx.billing.get_auto_topup() — auto-recharge configuration."""
+    enabled: bool = False
+    threshold_pct: int = 10
+    recharge_tokens: int = 20000
+    recharge_cents: int = 2000
+    payment_method_id: str = ""

imperal_sdk-5.4.0/tests/contract/test_artifacts_freshness.py

@@ -0,0 +1,101 @@
+"""Conformance A8/A9 — committed contract artifacts must match the live SDK.
+
+A8 (audit 2026-06-04, re-validated 2026-06-12): ``sdk_claims.json`` sat at
+5.1.0 while the SDK shipped 5.2.0/5.2.1/5.2.2 — the kernel-side
+``contract_guard`` freshness layer keyed on the stale pin and the lag was
+invisible to every local gate. A9: the docs_guard snapshots
+(``api_surface.json`` / ``ctx_surface.json``) had the same hand-copied-rot
+failure mode. These tests run under preflight Edge 1 (``tests/contract/``),
+so a stale committed artifact turns the one sanctioned gate red locally.
+"""
+from __future__ import annotations
+
+import dataclasses
+import json
+from pathlib import Path
+
+import pytest
+
+from imperal_sdk.devtools.generate_api_surface import generate_surface
+from imperal_sdk.devtools.generate_sdk_claims import generate_claims
+
+REPO = Path(__file__).resolve().parents[2]
+# imperal-sdk sits inside the MCP-Configs workspace checkout; standalone
+# clones (CI on GitHub) won't have the workspace-level docs_guard inputs.
+WORKSPACE_GUARD_INPUTS = REPO.parent / "scripts" / "docs_guard" / "inputs"
+
+
+def test_committed_sdk_claims_match_generated() -> None:
+    committed = json.loads((REPO / "sdk_claims.json").read_text(encoding="utf-8"))
+    assert committed == generate_claims(), (
+        "sdk_claims.json is stale — regenerate with: "
+        "python -m imperal_sdk.devtools.generate_sdk_claims --output sdk_claims.json "
+        "(and copy to kernel tools/contract/sdk-claims.json on deploy)"
+    )
+
+
+def test_docs_guard_api_surface_snapshot_fresh() -> None:
+    snap = WORKSPACE_GUARD_INPUTS / "api_surface.json"
+    if not snap.is_file():
+        pytest.skip("workspace docs_guard inputs not present (standalone SDK checkout)")
+    committed = json.loads(snap.read_text(encoding="utf-8"))
+    live = generate_surface()
+    assert {ns: sorted(m) for ns, m in committed.items()} == {
+        ns: sorted(m) for ns, m in live.items()
+    }, (
+        "scripts/docs_guard/inputs/api_surface.json is stale — refresh it from "
+        "imperal_sdk.devtools.generate_api_surface (manual-cp rot, conformance A9)"
+    )
+
+
+def _live_ctx_surface() -> set[str]:
+    """Public Context surface: dataclass fields + properties + methods.
+
+    Mirrors the original ctx_surface.json snapshot semantics (everything an
+    extension author can legitimately write after ``ctx.`` at the top level,
+    excluding kernel-injected attrs like ``secrets`` which are not part of
+    the dataclass).
+    """
+    from imperal_sdk.context import Context
+
+    fields = {f.name for f in dataclasses.fields(Context) if not f.name.startswith("_")}
+    members = {
+        name
+        for name, value in vars(Context).items()
+        if not name.startswith("_") and (isinstance(value, property) or callable(value))
+    }
+    return fields | members
+
+
+def test_kernel_contract_copies_mutually_consistent() -> None:
+    """A5: the two local copies of the kernel contract (the SDK contract-test
+    fixture and the docs_guard snapshot) must be identical — both are refreshed
+    from kernel ``tools/kernel-contract.json`` on a kernel contract change, and
+    one-sided rot (e.g. the pre-2026-06-12 state: guard copy carried the old
+    max_depth=3 while the fixture carried 6) is exactly how 'ALL GREEN'
+    overstates coverage."""
+    guard_copy = WORKSPACE_GUARD_INPUTS / "kernel-contract.json"
+    if not guard_copy.is_file():
+        pytest.skip("workspace docs_guard inputs not present (standalone SDK checkout)")
+    fixture = json.loads(
+        (REPO / "tests" / "fixtures" / "contract" / "kernel-contract.sample.json").read_text(
+            encoding="utf-8"
+        )
+    )
+    assert fixture == json.loads(guard_copy.read_text(encoding="utf-8")), (
+        "kernel-contract fixture and docs_guard snapshot diverged — refresh BOTH "
+        "from kernel tools/kernel-contract.json (conformance A5)"
+    )
+
+
+def test_docs_guard_ctx_surface_snapshot_fresh() -> None:
+    snap = WORKSPACE_GUARD_INPUTS / "ctx_surface.json"
+    if not snap.is_file():
+        pytest.skip("workspace docs_guard inputs not present (standalone SDK checkout)")
+    committed = set(json.loads(snap.read_text(encoding="utf-8")))
+    live = _live_ctx_surface()
+    assert committed == live, (
+        f"scripts/docs_guard/inputs/ctx_surface.json is stale (conformance A9). "
+        f"missing_from_snapshot={sorted(live - committed)} "
+        f"gone_from_sdk={sorted(committed - live)}"
+    )