imperal-sdk 5.2.1__tar.gz → 5.3.0__tar.gz

{imperal_sdk-5.2.1 → imperal_sdk-5.3.0}/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 All notable changes to `imperal-sdk` are documented here.
 
+## 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,
+submodule attribute, star-import and `dir()` entry resolves exactly as before
+(verified by an eager-parity test over the whole surface).
+
+### Changed
+
+- **The package root is now import-light (PEP 562 lazy surface).**
+  `import imperal_sdk` — and importing transport-free helpers such as
+  `imperal_sdk.chat.filters` or `imperal_sdk.chat.error_codes` — no longer
+  loads the HTTP client stack. Heavy dependencies load on first use of the
+  names that actually need them (`Context`, the service clients,
+  `get_llm_provider`, …). Benefits: faster cold imports, and helper modules
+  are now safe to import from restricted/sandboxed execution contexts that
+  forbid network-stack loading.
+
+Nothing to migrate — rebuild against `imperal-sdk>=5.2.2` at your convenience.
+
 ## 5.2.1 — 2026-06-01 — ChatExtension ergonomics & honest deprecations
 
 Small, fully backward-compatible cleanup of `ChatExtension`. No API removals;

{imperal_sdk-5.2.1 → imperal_sdk-5.3.0}/PKG-INFO

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

{imperal_sdk-5.2.1 → imperal_sdk-5.3.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.1 → imperal_sdk-5.3.0}/sdk_claims.json

@@ -1,5 +1,5 @@
 {
-  "_sdk_version": "5.1.0",
+  "_sdk_version": "5.3.0",
   "constants": {
     "max_call_depth": {
       "counts_root": true,
@@ -17,11 +17,21 @@
     "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"
     ]
   }
 }

imperal_sdk-5.3.0/src/imperal_sdk/__init__.py

@@ -0,0 +1,188 @@
+"""Imperal Cloud SDK — build extensions for the Imperal platform."""
+from typing import TYPE_CHECKING
+
+__version__ = "5.3.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
+# modules -> httpx) into EVERY consumer of ANY submodule — including
+# Temporal workflow code that lazily imports transport-free helpers such as
+# ``imperal_sdk.chat.filters`` (httpx subclasses urllib.request.Request,
+# which the workflow sandbox restricts; kernel federal
+# I-SANDBOX-SAFE-LAZY-IMPORTS, live incident 2026-06-10). The public
+# surface is unchanged: every name resolves to the same object, star-import
+# honors __all__, and resolved names are cached back into module globals.
+
+# name -> defining module (resolved on first attribute access)
+_LAZY_ATTRS = {
+    # Core
+    "Extension": "imperal_sdk.extension",
+    "ToolDef": "imperal_sdk.extension",
+    "SignalDef": "imperal_sdk.extension",
+    "ScheduleDef": "imperal_sdk.extension",
+    "LifecycleHook": "imperal_sdk.extension",
+    "HealthCheckDef": "imperal_sdk.extension",
+    "WebhookDef": "imperal_sdk.extension",
+    "EventHandlerDef": "imperal_sdk.extension",
+    "ExposedMethod": "imperal_sdk.extension",
+    "TrayDef": "imperal_sdk.extension",
+    "Context": "imperal_sdk.context",
+    "ImperalAuth": "imperal_sdk.auth",
+    "AuthError": "imperal_sdk.auth",
+    "User": "imperal_sdk.types.identity",
+    "UserContext": "imperal_sdk.types.identity",
+    "Tenant": "imperal_sdk.types.identity",
+    "TenantContext": "imperal_sdk.types.identity",
+    "generate_manifest": "imperal_sdk.manifest",
+    "save_manifest": "imperal_sdk.manifest",
+    "ChatExtension": "imperal_sdk.chat",
+    "ActionResult": "imperal_sdk.chat.action_result",
+    # LLM
+    "get_llm_provider": "imperal_sdk.runtime.llm_provider",
+    "LLMProvider": "imperal_sdk.runtime.llm_provider",
+    "LLMConfig": "imperal_sdk.runtime.llm_provider",
+    "LLMUsage": "imperal_sdk.runtime.llm_provider",
+    "MessageAdapter": "imperal_sdk.runtime.message_adapter",
+    # IPC
+    "ExtensionsClient": "imperal_sdk.extensions.client",
+    "CircularCallError": "imperal_sdk.extensions.client",
+    # Errors
+    "ImperalError": "imperal_sdk.errors",
+    "APIError": "imperal_sdk.errors",
+    "NotFoundError": "imperal_sdk.errors",
+    "RateLimitError": "imperal_sdk.errors",
+    "ValidationError": "imperal_sdk.errors",
+    "ExtensionError": "imperal_sdk.errors",
+    "QuotaExceededError": "imperal_sdk.errors",
+    "SkeletonAccessForbidden": "imperal_sdk.errors",
+    # Types
+    "Page": "imperal_sdk.types",
+    "ChatResult": "imperal_sdk.types",
+    "FunctionCall": "imperal_sdk.types",
+    "Document": "imperal_sdk.types",
+    "CompletionResult": "imperal_sdk.types",
+    "LimitsResult": "imperal_sdk.types",
+    "SubscriptionInfo": "imperal_sdk.types",
+    "BalanceInfo": "imperal_sdk.types",
+    "FileInfo": "imperal_sdk.types",
+    "HTTPResponse": "imperal_sdk.types",
+    "Event": "imperal_sdk.types",
+    "WebhookRequest": "imperal_sdk.types",
+    "WebhookResponse": "imperal_sdk.types",
+    "HealthStatus": "imperal_sdk.types",
+    # Protocol + Validator
+    "ExtensionProtocol": "imperal_sdk.protocols",
+    "validate_extension": "imperal_sdk.validator",
+    "ValidationReport": "imperal_sdk.validator",
+    "ValidationIssue": "imperal_sdk.validator",
+    "validate_source_tree": "imperal_sdk.validator_v1_6_0",
+    "validate_manifest_v1_6_0": "imperal_sdk.validator_v1_6_0",
+    # Secrets (importable from the root since 5.1.0; not in __all__ —
+    # preserved as-is)
+    "SecretSpec": "imperal_sdk.secrets",
+    "SecretClient": "imperal_sdk.secrets",
+    "SecretStatus": "imperal_sdk.secrets",
+    "SecretNotDeclaredError": "imperal_sdk.secrets",
+    "SecretWriteForbidden": "imperal_sdk.secrets",
+    "SecretVaultUnavailable": "imperal_sdk.secrets",
+    "SecretValueTooLarge": "imperal_sdk.secrets",
+    "SecretDeclarationConflict": "imperal_sdk.secrets",
+}
+
+# Any imperal_sdk submodule also resolves as a root attribute (the eager
+# imports used to expose chat/context/errors/ui/sdl/... as side effects;
+# the generic fallback in __getattr__ preserves that surface).
+
+if TYPE_CHECKING:  # pragma: no cover — IDE / type-checker surface only
+    from imperal_sdk.extension import (
+        Extension, ToolDef, SignalDef, ScheduleDef,
+        LifecycleHook, HealthCheckDef, WebhookDef, EventHandlerDef, ExposedMethod, TrayDef,
+    )
+    from imperal_sdk.context import Context
+    from imperal_sdk.auth import ImperalAuth, AuthError
+    from imperal_sdk.types.identity import User, UserContext, Tenant, TenantContext
+    from imperal_sdk.manifest import generate_manifest, save_manifest
+    from imperal_sdk.chat import ChatExtension
+    from imperal_sdk.chat.action_result import ActionResult
+    from imperal_sdk import ui
+    from imperal_sdk import sdl
+    from imperal_sdk.runtime.llm_provider import get_llm_provider, LLMProvider, LLMConfig, LLMUsage
+    from imperal_sdk.runtime.message_adapter import MessageAdapter
+    from imperal_sdk.extensions.client import ExtensionsClient, CircularCallError
+    from imperal_sdk.errors import (
+        ImperalError, APIError, NotFoundError, RateLimitError,
+        ValidationError, ExtensionError, QuotaExceededError,
+        SkeletonAccessForbidden,
+    )
+    from imperal_sdk.types import (
+        Page, ChatResult, FunctionCall,
+        Document, CompletionResult, LimitsResult, SubscriptionInfo,
+        BalanceInfo, FileInfo, HTTPResponse,
+        Event, WebhookRequest, WebhookResponse, HealthStatus,
+    )
+    from imperal_sdk.protocols import ExtensionProtocol
+    from imperal_sdk.validator import validate_extension, ValidationReport, ValidationIssue
+    from imperal_sdk.validator_v1_6_0 import (
+        validate_source_tree,
+        validate_manifest_v1_6_0,
+    )
+    from imperal_sdk.secrets import (
+        SecretSpec, SecretClient, SecretStatus,
+        SecretNotDeclaredError, SecretWriteForbidden, SecretVaultUnavailable,
+        SecretValueTooLarge, SecretDeclarationConflict,
+    )
+
+
+def __getattr__(name: str):
+    import importlib
+
+    src = _LAZY_ATTRS.get(name)
+    if src is not None:
+        obj = getattr(importlib.import_module(src), name)
+        globals()[name] = obj
+        return obj
+    if name.startswith("_"):
+        raise AttributeError(f"module 'imperal_sdk' has no attribute {name!r}")
+    try:
+        mod = importlib.import_module(f"imperal_sdk.{name}")
+    except ImportError:
+        raise AttributeError(
+            f"module 'imperal_sdk' has no attribute {name!r}"
+        ) from None
+    globals()[name] = mod
+    return mod
+
+
+def __dir__():
+    return sorted(set(globals()) | set(_LAZY_ATTRS) | {"ui", "sdl"})
+
+
+__all__ = [
+    # Core
+    "Extension", "ToolDef", "SignalDef", "ScheduleDef",
+    "LifecycleHook", "HealthCheckDef", "WebhookDef", "EventHandlerDef", "ExposedMethod", "TrayDef",
+    "Context", "ImperalAuth", "AuthError",
+    "User", "UserContext", "Tenant", "TenantContext",
+    "ChatExtension", "ActionResult",
+    "generate_manifest", "save_manifest",
+    # IPC
+    "ExtensionsClient", "CircularCallError",
+    # LLM
+    "get_llm_provider", "LLMProvider", "LLMConfig", "LLMUsage", "MessageAdapter",
+    # Errors
+    "ImperalError", "APIError", "NotFoundError", "RateLimitError",
+    "ValidationError", "ExtensionError", "QuotaExceededError",
+    "SkeletonAccessForbidden",
+    # Types
+    "Page", "ChatResult", "FunctionCall",
+    "Document", "CompletionResult", "LimitsResult", "SubscriptionInfo",
+    "BalanceInfo", "FileInfo", "HTTPResponse",
+    "Event", "WebhookRequest", "WebhookResponse", "HealthStatus",
+    # Protocol + Validator
+    "ExtensionProtocol", "validate_extension", "ValidationReport", "ValidationIssue",
+    "validate_source_tree", "validate_manifest_v1_6_0",
+    # UI
+    "ui",
+    # SDL — Structured Data Layer
+    "sdl",
+]

{imperal_sdk-5.2.1 → imperal_sdk-5.3.0}/src/imperal_sdk/billing/client.py

@@ -6,7 +6,10 @@ from dataclasses import dataclass
 from typing import Any
 import httpx
 
-from imperal_sdk.types.models import BalanceInfo
+from imperal_sdk.types.models import (
+    BalanceInfo, PaymentMethod, SetupIntentResult, ChangePlanResult,
+    TopupResult, PaymentRecord,
+)
 
 log = logging.getLogger(__name__)
 
@@ -53,7 +56,10 @@ class BillingClient:
 
     def _headers(self) -> dict:
         if self._service_token:
-            return {"X-Service-Token": 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:
@@ -160,3 +166,89 @@ class BillingClient:
         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,
+                    user: Any = None) -> TopupResult:
+        """Token top-up PaymentIntent. Surfaces errors."""
+        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},
+                                     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", ""))

{imperal_sdk-5.2.1 → imperal_sdk-5.3.0}/src/imperal_sdk/context.py

@@ -50,6 +50,13 @@ 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, user: Any = None): ...
 
 
 @runtime_checkable

{imperal_sdk-5.2.1 → imperal_sdk-5.3.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"],
+    "POST /v1/billing/payment-methods/setup": [],
 }
 
 

{imperal_sdk-5.2.1 → imperal_sdk-5.3.0}/src/imperal_sdk/types/models.py

@@ -123,3 +123,56 @@ 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 = ""
+
+
+@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 = ""

imperal_sdk-5.3.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)}"
+    )